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1, REAL PARTY IN INTEREST 



[37 CFR 4 1 .37(e)( ! }(}}] 

The real parties in interest are: 

DKR SoimdShore Oasis Holding Fund Ltd. 

do Codan Trust Companies (Cayman) Limited 

Century Yard, Cricket Square 

Hutchins Drive 

P.O. Box 2681 GT 

George Town, Grand Cayman 

KYI -1111. 

Cayman Islands 

and 

Trinad Capita! Master Fund, Ltd, 
do Charl ie Bentz. CFO 
2121 A venue of the Stars, Suite 2550 
Los Angeles, CA 90035 

2. RELATED APPEALS AND INTERFERENCES 

[37CFR4137(c)(i){ti)] 

There is a related appeal in application no, 10/086,268, 

3. STATUS OF CLAIMS 

[37 CFR4L37(c)(l)(n03 

The following claims have been rejected and appealed: claims 20-27 and 29-38. 
The following claims have been cancelled: 1-19 and 28. 
The claims on appeal are reproduced below in the Appendix at Section 9 of this 
Appeal Brie£ 

4. STATUS OF AMENDMENTS 

[3?CFR4137(c)(l)(iv)l 

No amendments were filed subsequent to final rejection, 

5- SUMMARY OF CLAIMED SUBJECT MATTER 

[37CFR4L37(c)(l)(v)j 



Atty. Docket No.: DKTRP002 Appln. No.: 10/086,262 

Page 2 



5 Independent Claim 20 

independent claim 20 is directed to an article of manufacture including at least 
one tangible medium having an. enterprise directory configured for IP telephony 
embodied thereon. See, tor example, [0085] * and the enterprise directory 90 in 
Fig. 3, The article of manufacture comprises an X>5QG enterprise directory embodied 
on the at least one tangible medium, the X.500 enterprise directory being a directory 
of named objects, including users, network devices and network services. See [0085] 
and [0086], 

The schema of the enterprise directory includes at least one object for 
representing a component of an IP telephony system, the component selected from a 
group consisting of a GateKeeper, a Gate way, a Multipoint Control Unit (MCU), a 
GateKeeper Exchange, and a user with associated telephony service attributes. These 
are. for example, schema extensions of the enterprise directory; See [0086], which 
states: 

[0086] In a preferred embodiment, the enterprise directory 90 is implemented 
using a genera! purpose directory such as NDS* The invention introduces 
schema extensions in NDS, The schema extensions enhance the NDS base 
schema so that it supports the Directory Services requirements for an R323 
Recommendation based IP telephony network, in addition to H.323 support, 
the schema extension enables the H.323 gatekeepers in an 1 1.323 IP telephony 
network to automatically find each other. This capability is not currently 
speeified and supported by the ITU H323 Recommendation vJ /The schema 
extensions also enable the invention to provide many of its unique features, 
eg, caller ID, follow me with call filtering, etc. 

Also, see [0033] and [Oi lS]. 

5,2, Independent Claim 21 

independent claim 21 is directed to a communication system . The sy stem 
includes a public switched telephone (PST) network (16, Figs, K 2, 57 and 58). The 
system also includes an internet protocol (IP) network (18* Figs, U 2, 49, and 58), A 
plu rality of gateway networks are coupled to the PS T network and the I P network, 
See, e,g„ 4, 6 and S in Fig, I « 

A n enterpr ise d irectory server is coupled to the plurality of gateway networks, 
the enterprise directory server comprising an enterprise directory that is a directory of 
named objects, including users, network devices and network services, and having an 

* for convenience* reference is made throughout this Appeal Brief to paragraphs of Applicant's 
published patent application no. 2003/0095541, published on May 22, 2003. 
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extensible schema- configured to provide data to support routing of telephone calls. 
This subject matter (including the extensible schema) is summarized above, with 
respect to independent claim 20, and so that summarization, is incorporated herein by 
reference with respect to summarizing this similar subject matter of independent 
claim 2 1 , See, also, reference numeral 28 in Fig, 2 and Fig, 3, particularly in Fig. 3 in 
which the directory server 28 is shown as including an enterprise directory 90 and 
NWAdmin9L 

I ndependent clai m 32 is di rected to a method of operat in g a communication 
system having a plurality of gateway networks coupled to an internet protocol (IP) 
network and to a public switched telephone (PST) network to route a telephone call 
over the IP network, 1 he com.munka.tion system itself is summarized above, with 
respect to independent claims 20 and 2 L and so that summarization is incorporated 
herein by reference with respect to summarizing this similar subject matter of 
independent claim 32. 

The method includes providing a directory server comprising an enterprise 
directory that is a directory of named objects, including users, network devices and 
network services and having an extensible schema configured to provide data to 
support routing of telephone calls. This subject matter { including the directory 
server) is summarized above, with respect to independent claim 2 i , and so that 
summarization is incorporated herein by reference with respect to summarizing this 
similar subject matter of independent claim 32, 

The method further includes accessing the directory server, including 
accessing the extensible schema of the enterprise directory, to create a plurality of 
gateway databases, each gate way database associated with one of the plurality of 
gateway networks and each gatew ay database comprising a list of telephone numbers 
that each of the pl u rality of gateway networks will accept. See, e.g., [0090]: 

[0090] Referring again to FIG, 3, the gateway database 51 is an open database 
connectivity (ODBC) compatible database. The gateway database 51 contains 
enterprise white pages, frequent contact information, gateway routing tables, 
individual user follow me records, and a call log. The gateway database 51 
records are folly indexed to provide necessary real-time performance. The 
enterprise directory 90 is the source of the white pages, and frequent contact 
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and raw routing tables. This information Is separately maintained in the 
gateway database because commercially available implementations of an 
enterprise directory, e,g, NDS> are not Indexed, and are therefore not easily 
searchable. The gateway database 51 is indexed to facilitate the availability of 
the data. The data is obtained from the enterprise directory 90 and passed to 
the gateway database 51 by the dredger 107, The gateway database 51 also 
includes an operational routing table, user follow me and call log data which 
are created within the gateway server 26. 

The method further includes accepting a telephone number entered by the 
user, and accessing the gateway database associated wi th the gateway network to 
determine which of the plurality of gateway n etworks wili accept the telephone 
number entered fay the user. The telephone eat is muted from the calling telephone 
over the IP network. See, e.g., [0145] to [0148]. See, also, [0159] to [0161]. 



Independent claim 38 is directed to a communication system including a 
public switched telephone network and an internet protocol network, T his subject 
matter is summarized above, with respect to independent claim 2 L and so that 
summarisation is incorporated herein by reference w ith respect to summarising this 
similar subject matter of independent claim 38, 

Independent claim 38 is further directed to a plurality of voice gateways, and 
to general purpose enterprise directory services comprising a distributed group of 
directory servers coupled to the plurality of voice gateways. See, e.g., 4, 6, and 8 in 
Figs. 1 and 2. See, also, 26 (gateway server) in Fig, 2, See, also, 28 m Fig, 2 
(directory server). 

The directory services comprises an enterprise directory that is a directory of 
named objects, including users, network devices and network services and having an 
extensible schema configured to provide data to support routing of telephone calls 
and configured to provide data to support routing of telephone calls over the IP 
network. The enterprise directory has an extensible schema including at least one IP 
telephony object selected from a group consisting of an object configured to represent 
a GateKeeper, an object configured to represent a Gateway; an object configured to 
represent, a Multipoint Control Unit; an object configured to represent a GateKeeper 
Exchange, and an object configured to represent communication system user with 
associated IP telephony services attributes. As a result, a single point of entry is 
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provided for making additions, changes and deletions of the IP telephony objects by 
making additions, changes and deletions in the schema of the enterprise di rectory 
services. This subject matter is summarized above, with respect to independent claim 
29, arid so that summarization is incorporated herein by reference with respect to 
summarising this simitar subject matter of independent claim 38, 



6, GROUNDS OF REJECTION TO BE REVIEWED ON APPEAL 

[37CFR41.37(e)(l)(vi)3 

Groun d J: 

Claim 20 is rejected under 35 US.C 10L 
Ground II; 

Claims 2 L 27 and 29-31 are rejected under 35 U.S.C 102(e) as being 
anticipated by Krishnaswanvy (USP 6909708), 



Ground 111: 

Claims 22-26 are rejected as being obvious over Krbhnaswamv in 
view of Guy (USP 6870827), 



Ground IV: 

Claims 32-37 arc rejected as being obvious over Krishnaswamy in 
view of Curry (USP 6078582). 



Ground V: 

Claims 20 and 38 are rejected as being obvious over Krishnaswamy in 
vicwofRainis(USP 6310873), 



7, ARGUMENT 

[37CFR4K37(c)(I)(vii)) 
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7J, Ground I 



7 J. I CklmM 

The Examiner con tends thai claim 20 is directed to a data structure of a 
database thai does not Ml within any of the four categories of statutory subject 
matter. However, because what the Examiner contends Is a "'data structure' 7 is 
embodied on a tangible medium and produces functional advantages, the claimed 
subject matter h statutory ~ not mere printed matter. 

In particular, claim 20 is directed to an article of manufacture. Furthermore, 
the "enterprise di rectory 5 ' (not a database, as discussed be Sow with respect to the prior 
art based rejections) embodied thereon produces functional ad vantages that disappear 
if the same data is recorded in a different format. According to the In Re Lowry case 
and cases following it this is sufficient to distinguish a claimed invention from what 
might otherwise be considered unpatentable "printed matter," More particularly, that 
the enterprise directory embodied on the article of manufacture produces functional 
advantages that disappear if the same data is recorded in a different format indicates 
that the claimed format has a functional significance that can be separated from its 
data recording contents. 

Examples of such functional significance pervade Applicant 's specification. 
As just one example, see paragraph [0086] of the published version of Applicant's 
specification, which discusses: 

[ 0086] In a preferred embodiment, the enterprise directory 90 is implemented 
using a genera! purpose directory such as NDS> The invention introduces 
schema extensions in NDS* "File schema extensions enhance the NDS base 
schema so that it supports the Directory Services requirements for an H323 
Recommendation based I P telephony network. In addition to H323 support, 
the schema extension enables the H 323 gatekeepers in an HL323 IP telephony 
network to automatically find each other. This capability is not currently 
specified and supported by the ITU H323 Recommendation v J > The schema 
exte nsions also enable the inve ntion to prov ide many of its unique features, 
e.g. caller ID, follow me with call filtering, etc. 

Since the claimed format has a functional significance that can be separated from its 

data recording contents, claim 20 recites patentable subject matter under 35 DSC 101 , 
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7.2, Ground II 



7 J. I Claims 2 L 27 and 29-31 
The Examiner contends thai claims 21, 27 and 29-31 recite subject matter 

disclosed by Krishnaswamy. In part, in using the Krishnaswainy patent to reject the 

claims, the Examiner is contending that Kmhnaswamy's disclosure of a "database" 

anticipates the '"enterprise directory"' feature in Applicant's claims. It is noted that the 

Examiner does not contend that Krishna swamy*s disclosure of a database renders 

obvious the "enterprise directory'' feature in Applicant's claims. For example, in 

rejecting claims 21, 27 and 29-31 as anticipated, the Examiner notes in part (see page 

3 of the Final Office Action, dated December 20. 2007* in Item 5): 

and an enterprise directory server (Fig, 1.9F, Directory is enterprise 
directory server or Fig. \ OA, Ref L 2^ 3) coupled to the plurality of gateway 
networks, the enterprise directory server comprising an enterprise directory 
that is a di rectory of named objects* including users, network de v ices and 
network services and having an extensible schema configured to provide data 
to support routing of telephone calls (Fig, 1 OB, Ref enterprise Directory server 
1082, user profile, telephone gateway and email address etc. and Fig. 3 OA, 
Ref 1-3). 

The claim 21 subject matter not on!y recites an "'enterprise directory" — not a 
database *■* but. further, recites the following about the enterprise directory: "wherein 
the enterprise directory is a directory of named objects, including users, network 
devices and network services." Yet further, the enterprise directory is "enhanced" 
with an extensible-schema to provide data to support routing of telephone calls," such 
call routing features previously otherwise only being available using database (i.e., 
table-based) structures. For example. Applicant's specification discloses that the 
"network devices" of the enterprise directory may include "e,g. routers, gateways" 
and the "network services" of the enterprise directory may include "e.g. print 
servers/" That is, the enterprise directory is, for example, an industry-standard 
genera! purpose directory, extended with schema for controlling call routing features. 

Basically, Applicant does not agree that the Krishnaswamy reference discloses 
the "enterprise directory" recited in the claims. In addition, Applicant does not agree 
with the Examiners assertion that the distinction between what is claimed and what 
is disclosed by Krishnaswamy must be explicitly made in Applicant's specification in 
order for such a distinction to exist. During prosecution of the application, for 
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example, as mentioned in the Examiner interview Summary included in Amendment 
C filed on August 14 2007, the Examiner has argued that Applicant's specification 
docs not distinguish between a "database" and an Enterprise directory'* and that, 
therefore, the Examiner is free to apply the "database*" of Krishnaswamy against the 
"'enterprise directory" recited in the claims. T he Examiner also made such an 
argument at pages I I and 1 2 of the Final Office Action, 

As discussed in detail below, it is respectfully submitted that Applicant has 
demonstrated that one of ordinary skill in the art around the time of the application 
filing would readily distinguish the Krishnaswamy "database*' from the "enterprise 
directory*' recited in Applicant's claims. As also discussed in detail below. It is 
further respectfully submitted that there is no requirement for Applicant's 
specification to explicitly distinguish between a "database" and an "enterprise 
directory ." If this was the case, then applicants would be requ ired to predict e very 
rejection an Examiner may present, drafting and presenting rebuttal distinguishing 
language in the specification, even before the patent application has been filed. 
Clearly, this cannot be the requirement. 

Thus, Applicant once again respectfully submits that the "database'* of 
Krishnaswamy does not anticipate the "'enterprise directory" (with extensible schema) 
recited m the claims. It is respectfully submitted that it is the Examiner who has the 
initial burden to demonstrate that each and every element as set forth in the claim is 
found, either expressly or inherently described, in a single prior art reference. Here, 
the Examiner has not demonstrated that the Krishnaswamy "database" anticipates the 
"enterprise directory" (with extensible schema) recited in the claims. It is 
respectfully submitted that the anticipation rejection is improper for at least this 
reason alone. 

The Term "Enterprise directory Cannot he Properly Cominml to The "Directory 

Even though it is not Appl icant 's burden to do so, in the interest of furthering 
prosecution and supplementing the record, Applicant has provided to the Examiner 
evidence that the Krishnaswamy "directory services" does not anticipate the 
"enterprise directory^ (with extensible schema) recited in the claims. Applicant did 
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this by way of providing several references from about the time of Applicant' $ 
priority date. 

! , T. Howes and M Smith, LDAP: Programming Directory Enabled 
Applications with Lightweight Directory Access Protocol MacmiUan Technology 
Series, 1997. In addition to the cover and publication pages. Applicant provides 
herewith an excerpt at pages 4-5, See Appendix A of the Evidence Appendix, In the 
excerpt* in the section entitled "What a Directory Service is Not," it is clearly stated 
that a directory serv ices is not a general purpose database, While this entire section is 
provided in Appendix A, Applicant would like to draw attention to one particular 
paragraph: 

The first thing you should not do is treat the directory like a general database. 
It's not designed with that kind of use in mind, and yotrll likely he 
disappointed with the results. This means the directory is not suited to 
prov ide transaction-based service, cannot generally handle huge numbers of 
updates, and usually would make a bad engine for an SQL application. 

2, United States Patent No. 6*0 1 6,499, assigned on its face to Novell Inc. The 
filing date of the priority provisional application is February 20, 1997, and the filing 
date of the non-provisional application is July 21, 1997, At col L line 60 et seq, for 
example, the applicant distinguishes between "directory services" and "relational 
databases." 

Unlike relational databases, "directory service" structures are a relatively 
recent development in information technology. The need for directory services 
became clear only after computer networks became a prominent part of the 
information landscape and grew so large and complex that their administration 
required full-time attention from specialists. Directory services are sometimes 
referred to as "naming services/' 

A variety of directory service providers are now available to help administer 
both the location of network resources and the rights of network users to use 
those resources. Many, but not all, directory service tools conform at least in 
part with the X.50G directory services standard. One well-known directory 
service system includes NetWare Directory Services software commercially 
available from Novell lite, of Prove, Utah (NET WARE DIRECTORY 
SERVICES is a trademark of Novell, Inc.), As used herein, "Novell Directory 
Services" ("NDS") includes NetWare Directory Services and any other 
directory service commercially available from Novell Inc. 

in contexts other than the present one, a directory services repository is 
sometimes called a directory services "database*" Both repositories and 
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databases may be distributed becau se that is mainly a matter of storage and 
locks for enforcing consistency, rather than a question of the basic internal 
structure, But "database'' and "repository" are not interchangeable in the 
present context, 

A repository supports naming services. Each repository is organized 
hierarchically, as one or more trees. Bach object in a tree (except the root 
object) has exactly one parent. Objects may generally have children, which 
may inherit properties from their ancestor objects. Objects are instances of 
"classes/ 1 as described in detail below, 

By contrast "database" as used herein refers to a relational database, A given 
database may support any of a wide variety of commercial or personal 
acti vities* Each database is organized as a set of tables in wh ich rows 
represent records and columns represent record fields. Certain fields may be 
found in multiple tables, and the values of these "key" or "index" fields are 
used to guide database searches. Database access and manipulation involve 
combining information from various tables into new combinations to obtain 
different views of the data. 

In short, databases and repositories arose at different times to meet different 
needs, and have different structures and capabilities. There is no need to dwell 
further here on the detai ls of relational database structure, SQL, or ODBC, as 
numerous references on those topics are widely available. Many computer 
science professionals have also taken at least one course in databases. 

3, The SLAPD and SLURPD Adm inistrator 's Guide, Uni versity of Michigan, 30 
April 1996, Release 3.3, In addition to the coven publication pages and Table of 
Contents, Applicant provides herewith an excerpt at pages 1-10. See Appendix B of 
the Evidence Appendix, In the excerpt in the section entitled "LI What Is a 
directory service?" it is discussed how a directory service differs from a database. The 
entire section 1.1 (two paragraphs only), is reproduced below: 

hi What m a directory service? 

A directory is like a database, but fends to contain more descriptive, attribute- 
based information. Flic information in a directory is generally read much more 
often than it is written. As a consequence, directories don't usually implement 
the complicated transaction or roll-back schemes regular databases use for 
doing high-volume complex updates. Directory updates are typically simple 
all-or-nothing changes, if they arc aliowed at all. Directories are tuned to give 
quick-response to high-volume lookup or search operations. They may have 
the ability to replicate information widely in order to increase availability and 
reliability, while reducing response time, When directory information is 
replicated, temporary Inconsistencies between the replicas may be OK, as long 
as they get in sync eventually. 
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There are many different ways to provide a directory service. Different 
methods allow different kinds of Information to be stored in the directory, 
place different requirements on how that information can be referenced, 
queried and updated, how it is protected from unauthorized access, etc. Some 
directory services are local, providing service to a restricted context (e.g. s the 
finger service on a single machine). Other services are global, providing 
service to a much broader context (e*g,, the entire internet). Global services 
are usually distributed, meaning that the data they contain is spread across 
many machines, ail of which cooperate to provide the directory service. 
Typically a global service defines a uniform namespace which gives the same 
view of the data no matter where you are in relation to the data iisel£ 

The Krisbnaswaniy ''database," on the other hand, is asserted by the Examiner 
to be the directory 1 934 in Fi«. 19F or DIR SVE! , DIR SVB2 or DIR. SVE3 in Fig, 
H)A< The discussion of Pig* I OA in the Krishnaswamy text does not even mention 
DIR SVEL DIR SVE2 or DIR SVE3 so it is not clear that this disclosure is even 
enabling such that it can be applied as anticipating the subject matter recited in the 
claims. The Krishimswamy text discussing Fig. 10A does mention: 

Directory services for muting telephone calls and other information Is 
provided by the directory services 1031 which is shared between the Public 
Branch Exchanges 104 U 1040 and the PSTN. 

The ''directory services 103 1 " appears to be strictly concerned with call routing and* 
for example, is not disclosed as "a directory of named objects, including users, 
network devices and network services/' Yet further, the enterprise directory recited 
in the claims is "enhanced" with m extensible-schema to provide data to support 
routing of telephone calls;' such call routing features previously otherwise only being 
available using database (i.e., table-based) structures, Call routing appears to be the 
primary purpose for the directory services J 03 1 disclosed by Krishuaswamy and, 
thus* the directory services 103 ! is not '"enhanced" for this function. Nor is there any 
indication in Krishnaswamy that the DIR S VE L DIR SVE2 or DIR SVE3 fit the 
recitation of **a directory of named objects, including users, network devices and 
network services" or being ^enhanced" with an extensible-schema to provide data to 
support routing of telephone calls. 

The Krishnaswamy "directory 1934" illustrated in Fig. 19F is disclosed by 
Krishnaswamy as being a directory services database. The discussion of this block in 
Krishuaswamy is scant limited to, at cob 23, lines 5-27 (emphasis added): 
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FIG. 19F is a block diagram of an internet telephony system in accordance 
with a preferred embodiment, A number of computers 1900, 1901, 1 902 and 
1903 are connected behind a firewall 1905 to the Internet 1910 via an Ethernet 
or other network connection. A domain name system 1906 maps names to IP 
addresses in the Internet 1910. Individual systems tor billing 1920, 
provisioning 1922, directory services 1934, messaging services 1930, such as 
voice messaging 1932 are all attached to the internet 1910 via a 
communication link. Another communication link is also utilized to facilitate 
communications to a satellite device 1 940 that is used to communicate 
information lo a variety of set top devices 1941-1943, A web server 1944 
provides access for an order entry system 1945 to the internet 1910. 

hi mi embodiment, the order entry system 1945 generates complete profile 
information for a given telephone number, including, name, address, fax 
number, secretary's number, wife's phone number, pager, business address, e~ 
mail address, IP address and phonemail address. This information is 
maintained in a database that can be accessed by ever} one on the network 
with authorization to do so. In an alternate embodiment, the order entry 
system utilizes a web interface for accessing an existing directory service 
database 1934 to provide information for the profile to supplement user 
entered information. 

Nothing here, either, discloses that the "directory 1934" (the label used in Fig. 19F) 
or directory services database 1934" (the label used in the Krishnaswarny text 
describing Fk, 19F) is "a d irectory of named objects, incl uding users, network 
devices and network services'" or, further, that is "enhanced" with an extensible- 
schema to provide data to support routing of telephone calls/' 

In addition, the three pieces of evidence from around the time of the filing of 
the present patent application, excerpts of which are provided above, also make this 
message consistently clear. The "enterprise directory'' recited in the claims is not a 
'"directory services" as that term is used in Krishnaswamy (and as that term can be 
best understood, gi ven the non-existent to scant disclosure of KrisJmaswamy) and 
which is relied upon by the Examiner in rejecting the claims. 

The Examiner is Incorrect m the Requirement Stated During the July 23 y 2007 
IpierviewJniheA^ 

Argmnents Section of the Final Off we Act ion in the Pre sent Application, that 

as used in Kmhnamamy and an 'Enterprise Directory^ m used in A pplicant $ 
Claims 
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We now discuss the Examiner's contention thai Applicant's specification 
must show the difference between a "'database-' and an "enterprise directory; * As 
mentioned above, this contention was made in both the July 23, 2007 Examiner 
interview In the present application and related application (10/086,268), as well as in 
the Advisory Action in the present application, and in the Final Office Action in the 
present application. Actually, again mistakenly asserting that Applicant's claims 
recite a "database," the Examiner eonciusoriiy states in the Final Office Action, at 
pages 1 1 and 12, 'The directory data of the prior art and enterprise directory of 
applicant are not different because the specification of the application does not show 
the different [sic] between the databases because the applicant provides considerable 
details on the directory service in the response * these information do not appear in the 
specification or anywhere else in the application. Arguments of applicant can not 
take place of evidence lacking in the specification or anywhere else in the 
application" 

In refuting the Examiner's requirement about what the specification must say, 
we specifically refer to MPEP 21 1 1 ,01 and legal support referred to therein, which 
di scusses the subject of ascri bing the "plai n meaning" to cl aim terms. For example, 
in Amendment C, Applicant pointed out without extensive discussion or support 
that: 

It is respectfully submitted that there is no such requirement for Applicant's 
specification to distinguish between a "database** and an "enterprise 
directory /' If this was the case, then applicants would be required to predict 
every rejection an Examiner may present and provide rebuttal distinguishing 
language in the specification, even before the patent application has been 
filed. Clearly, this cannot be the requirement, 

Given that the Examiner continues to require that Applicant's specification 

distinguish between a "database" and an "enterprise directory" {such as in the 

Advisory Action and in the Final Office Action of the present patent application)* 

Appl ican t n o w discusses in greater detail the concept of "plain meaning'' and 

"ordinary and customary meaning" attributed to a term by "those of ordinary skill in 

the art/' More particularly. Applicant discusses MPEP 21 1 1 .01 and some Federal 

Circuit cases on the same point as rebuttal to the Examiner's requirement that 

Appl leant - s spec i treat ion must show the difference between a database having the 
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properties disclosed m KHshnaswamy and an enterprise directory as recited In the 
claims. 

For example, MPEP 2 I 1 L01 quotes the Eh|{|ij>s^AWH^^, reciting "[TJhe 
ordinary and customary meaning of a claim term is the meaning the term would have 
to a person of ordinary skill in the art in question at the time of the invention, Le. t as 
of the effective filing dale of the patent application/' MPEP 2 1 1 LO 1 also quotes the 
BlSSlMli^^ case, reciti ng "In the absence of an 

express intent to impart a novel meaning to the claim terms, the words are presumed 
to take on the ordinary and customary meaning attributed to them by those of 
ordinary skill in the art." As a last example, MPEP 21 1 1 .01 also quotes the ACTV, 
Inc. v. The Wait Disney Company case, which recites "Since there was no express 
definition for the term *URL* in the specification, the term should be given its 
broadest reasonable interpretation consistent with the intrinsic record and take on the 
ordinary and customary meaning attributed to it by those of ordinary skill in the 
art,,,/* 

Thus, MPEP 2111 .0 i and the eases cited therein implore the Examiner to use 
the "ordinary and customary meaning'- attributed to the term "enterprise directory" 
absent some indication on the part of Appl icant to impart a novel meaning to the 
term. Put another way; unless the Applicant intends for the term "enterprise 
directory" to have a meaning other than the "ordinary and customary" meaning, there 
is no requirement for Applicant to explicitly define the term "enterprise directory" in 
the specification and/or, most significantly, distinguish the term from "database" as 
used, for example, in Krishnaswamy. 

As Applicant has pointed out in great detail the "ordinary and customary 
meaning" attributed to the term "enterprise directory" is not covered by a database 
and, in fact* explicitly disclaims the notion of being covered by a database, 
particularly the databases disclosed by Krishnaswamy, The Examiner has refused to 
consider A pplicant' s pro vided evidence of such, instead insisting that Application 
should have foreseen the argument the Examiner would make regarding the term 
'"database/' 
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Perhaps the Examiner is mixing in the doctrine of " A patentee may be his own 
lexicographer/* In accordance with that doctrine, MPEP 21 I KOI cites the In re 
Eaufesa case, reciting that (emphasis added) an "inventor may define specific terms 
used to describe invention, hot must do so 'with reasonable clarity, deiiberateness, 
and precision' and, if done , must "set out his uncommon definition in some manner 
within the patent disclosure "*so as to give one of ordinary skill in the art notice of the 
change' in meaning," However, this requirement for the Applicant to define specific 
terms in the specification does not apply where the Applicant is not making an 
"uncommon definition" to change the meaning of terms from what would be the 
ordinary and customary meaning, linn is. Applicant is not changing the meaning of 
the term "enterprise directory" from what is the ordinary and customary meaning as 
evidenced, for example, by the various references cited to the Examiner above and 
provided herein in the appendices. 

Given all this, perhaps the Examiner does in feet believe that a reasonable 
Interpretation of 'enterprise directory" is broad enough to be covered by the databases 
disclosed by Krishnaswamy, but the Examiner has not asserted this, MPEP 2111 ,01 
discusses, again referring to the Phillips v, AWH case, "The ordinary and customary 
meaning of a term may be evidenced by a variety of sources, including 'the words of 
the claims themselves, the remainder of the specification, the prosecution hi story* and 
extrinsic ev idence concerning relevant scientific principles, the meaning of technical 
terms, and the slate of the art,'" Of course, as discussed above. Applicant believes 
that all. these sources* and particularly the extrinsic evidence, make clear, contrary to 
what may be the Examiner's belief, that the ordinary and customary meaning of 
Enterprise directory" is not broad enough to be covered by databases disclosed by 
Krishnaswamy and cited by the Examiner. 

Applicant recognizes thai, in other circumstances, it may be proper to look to 
a patent specification to find evidence of the intended meaning of a claim term when 
there are two or more commonly accepted meanings of the claim term, in the correct 
context, this situation would be limited, though, to the circumstance referenced in 
MPEP 211 1.01 in which the evidence of ordinary and customary meaning is 
ambiguous. This is not the case here. Referring to the 8jxx^]l|^ok ease, MPEP 
21 1 1 .01 states extrinsic sources, such as dictionaries, evidence more than one 
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definit ion for the term, the intrinsic record must be consulted to identify w hich of the 
different possible definitions is most consistent with applicant's use of the terms/* 
Also, referring to the Renis^ MPEP 
21 1 1 .01 states ''Where there are several common meanings for a claim term, the 
patent disclosure serves to point away from the improper meanings and toward the 
proper meanings/" fa this ease, the Examiner has not pointed out multiple common 
meanings for Enterprise directory" as recited in the claims, 

Applicant has pointed out several items of extrinsic evidence to support the 
definition of '"enterprise directory" as distinct from a database such as disclosed by 
Krishnaswamy and cited by the Examiner. If the Examiner continues to require 
Applicant's specification to explicitly define the "enterprise directory'" claim term, 
then Applicant respectful iy requests the Examiner to point out in support of the 
requirement evidence of another ordinary and customary meaning of "enterprise 
directory-' that may include a database such as disclosed by Krohn&swamy. 

In the absence of such a showing by the Examiner, it is respectfully submitted 

that: 

* The ordinary and customary meaning of "enterprise directory" is 
unambiguous, as ev idenced hy the several items of extrinsic ev idence pointed 
out by Applicant; 

♦ Since the ordinary and customary meaning of "enterprise directory" is 
unambiguous, these h no independent reason to look to Applicant's 
specification to identify a particular meaning intended by Applicant, 

The ordinary and customary meaning of "enterprise directory" cannot be construed to 

include a database such as the databases disclosed (cursorily) by Krishnaswamy, 

That said, contrary to the Examiner's assertions, it should be noted that, even 
in Applicant's specification, the "enterprise directory" is distinct from a database, and 
there is no evidence of an express intent to impart a novel meaning to the claim term 
^enterprise directory / % Thus, the words are presumed to take on the ordinary and 
customary meaning attributed to them by those of ordinary skil l in the art, which 
meaning has been amply demonstrated. 

For example, at [0092] of Applicant's speci fication^ it is stated that (emphasis 

added); 
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The preferred embodiment of the invent ion includes the X*50G compatible 
enterprise directory « However, in installations which do not have an X.5O0 
compatible enterprise directory, the alternative embodiments of the gateway 

iMM^^f*^ For 
example, one alternate embodiment may be used in systems which have an 
SQL Server database. The schema extensions may be added to the existing 
data structures in the SQL database, or a new, comprehensive schema may be 
established. 

Rather than showing an express intent to impart a novel meaning to the ^enterprise 
directory'' claim term, this section at [0092] of Applicants specification is entirely 
consistent with the understanding of one of ordinary skill in the art that an "enterprise 
directory " is not a database, since the database is described as being "one alternate 
embodiment" to an enterprise directory embodiment. 

Referring further to [0093] of Applicant's specification, an alternate 
em bodimen t (a "database designated the master database" ) of an enterprise d irectory 
is set forth. Notably, though, the embodiment described in [0093] does not describe 
the "master database" as being a directory "of named objects, including users, 
network devices and network services " as the enterprise directory is explicitly recited 
in claims I aod 5, This paragraph [0093] merely states, in its entirety: 

In a second alternative embodiment the enterprise directory includes a 
database designated the master database at a first location, and duplicate 
databases, designated slave databases at the remaining locations in the 
gateway network. In this master-slave configuration, all database 
administration is performed on the master database, Updates to the master 
database are exported to a file which is sent to the other locations and 
imported into the slave databases. The dredging and synchronization process 
would be the same as for an X.,500 compatible enterprise directory. The 
database cache 108 is a repository of information contained in RAM in the 
gateway server 26. The database cache includes data duplicated from the 
gateway database 5 1 which data is required to be in RAM to support the 
performance of the gateway server, and also transient/dynamically changing 
data, eg. idle/busy status of users' telephones. Much of the data In the 
database cache 108 is indexed for rapid retrieval. The gatekeeper agent 52 is 
the equivalent of an H.323 gatekeeper client 

Since the "master database** is not disclosed as being a directory "of named objects, 

including users, network devices and network services" as the enterprise directory is 

explicitly recited in claim 2 1 , this statement does not show an intent by the Applicant 

to set forth an "uncommon definition" of the term "enterprise d i rectory*- that is "a 



Atty. Docket No.: DKTRP002 



Page 18 



Appln. No.: 10/086,262 



directory of named objects, including users, network devices and network services" 
so as to give am of ordinary skill in the art notice of an intended change in meaning; 4 

Given the absence in the cited references of a disclosure or suggestion of an 
"enterprise directory, wherein the enterprise directory is a directory of named objects, 
including users, network devices and network services/' it is respectfully submitted 
that claim 21 , and claims 27 and 29-3 1 , which depend on claim 2 K is patentable over 
Krishnaswamy. 

Applicant has thus amply demonstrated that the Krishnaswamy "database** 
does not anticipate the "enterprise directory-' (with extensible schema) recited in 
claim 21. 

7.3, Ground 10 

7J.L Claims 22-26 

For the patentability of claims 22-26, Applicant relies herein on the 
patentability of claim 2 L on which these claims depend, 

7.4. Ground IV 

7J. L Claims 32-3? 
Like claim 2 L ciaims 32 -37 include the recitation of "an enterprise directory 
that is a directory of named objects, including users, network devices and network 
services and having an extensible schema configured to provide data to support 
routing of telephone calls/' Furthermore* the allegations of the Examiner with respect 
to claims 32-37 parallel the allegations made against claim 2 1 - U% applying the 
KrisMaswamy reference in the same or similar way. 

Thus, in refutation of the rejection of claims 32-37, Applicant incorporates the 
arguments made abo ve with reference to the rejection of claim 2 L as if those 
arguments were made herein in their entirety, 

J it is rsoted that, at [0085} of Applicant's specifteatioiu it is stated that "the enterprise directory 90 Ls a 
compan) -wide genera! purpose directory or global database of named objects including users* network 
devices (e.g. routers, gateways), mi network, services (e,g, print servers)." However, \hh isolated 
statement using the term "database* does not give orse of ordinary skill m the aft notice that the 
Applicant intends an "uncommon, definition'" that if taken Ons way, would be entirely inconsistent 
with the remainder of the specification. let alone the ordinary and customary meaning "as evidenced by 
a variety of sources* 
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7 - 5* ^ Claims 20 and 38 
With regard to claims 20 and 38, these claims recite not only enterprise 
directory that is a directory of named objects* Including users, network devices and 
network services and having an extensible schema configured to provide data to 
support routing of telephone calls" but, also, recite that the enterprise di rectory is an 
"X.500 compatible enterprise directory'' (claim 20) or further include "a single point 
of entry is provided for making additions, changes and del etions of the IP telephony 
objects by making additions, changes and deletions in the schema of the enterprise 
directory services" (claim 38). 

in the first place, as discussed above with reference to the rejection of claim 
2h it is respecttldiy submitted that Krishnaswamy (the primary reference) does not 
disclose "an enterprise directors' that is a directory of named objects, including users, 
network devices and network services and having an extensible schema con figured to 
provide data to support routing of telephone calls/' contrary to the Examiner's 
assertions. Thus, in refutation of the rejection of claims 20 and 38; Applicant 
incorporates the arguments made above with reference to the rejection of claim. 2 U as 
if those arguments were made herein In their entirety, 

Furthermore, the Examiner contends that it would be obvious to modify 
Krlshnaswamy in view of Rainis in order to yield the subject matter of claims 20 and 
38, stating "The motivation would have been to turn the internet into a multimedia 
network in order to reduce the cost of a telephone call/' Given the deficiency of 
Krishnaswamy, this is a moot point in any event. Applicant respectfully contends 
that the Examiner's stated motivation for modify ing Krishnaswamy in view of Rainis 
is woefully inadequate. 

Even under the &SR case, there must be some evidence, beyond the 
Examiner's mere eoaciusory statement, that one or ordinary skill m the art would be 
motivated to modify a primary reference in view of a secondary reference. The 
Examiner has not pointed to knowledge held by one of ordinary ski JI in the art that 
would have suggested the motivation, Applicant understands that KSR has obviated 
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the requirement of a rigid teaclvi ng-suggestlcni-moth ation (TSM) test. However, 
KSR has not completely eliminated the TSM test For example, see United Stales 
Court of Appeals for the Federal Circuit Opinion 2007-1223, ORTHO-MCNEIL 
PHARMACEU nCAU INC. v. MYL AR At page 1 L the Federal Circuit discusses: 

As this court has explained, however, a flexible TSM test remains the primary 
guarantor against a non-statutory hindsight analysis such as occurred in this 
ease. In relranslogic lech., Ine, 504 FJd 1249, 125? (Fed. Or. 2007) ("[A]s 
the Supreme Court suggests, a flexible approach to the TSM test prevents 
hindsight and focuses on evidence before the time of invention."). The TSM 
test, flexibly applied, merely assures that the obviousness test proceeds on the 
basis of ev idence - teachings, suggestions (a tellingly broad term), or 
motivations (an equally broad term) - that arise before the time of invention 
as the statute requires. As KSR requires, those teachings, suggestions, or 
motivations need not always be written references but may be found within 
the knowledge and creati vity of ordinarily skilled artisans. 

Contrary to the teaching of QSho^McNei], then, the Examiner's eonclusory statement 

clearly employs hindsight reasoning, since it is a mere statement of what the 

motivation for modifying Krisbnaswaniy would allegedly be, without providing any 

evidence of such, a motivation. 

Beyond that. Applicant has provided extensive evidence of non-obviousness, 
evidence which has not been refuted by the Examiner. In particular, the references 
cited above eiearfy point out why, to one of ordinary skill in the art, an enterprise 
directory (such as an X.500 compatible enterprise directory or an LDAP enterprise 
directory) is not interchangeable with what appears to be a standard database as 
disclosed by Krishnaswamy, Therefore, not only has the Examiner not set forth a 
sufficient prima facie ease of obviousness with respect to claims 20 and 38 but also, 
Applicant has refuted the Examiners allegation of obviousness with very strong 
evidence of non-obviousness. 
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8. CONCLUSION 

In view of the foregoing, it Is respeetftiily submitted that the Examiner's 
rejections of claims 20-27 and 29-38 are erroneous, Accordingly, the rejections 
should be reversed. 



R e spec t Ri 1 ! y sit bm itted, 
BEYER LAW GROUP LLP 

/ASH/ 

A San S. l iodes 
Registration No. 38,1.85 

BEYER LA W GROUP LLP 
Attorneys for Appellant 
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9. CLAIMS APPENDIX 

[3?CFR4L37(c)(1)(vni)] 

CLAIMS ON APPEAL 

20. An article of manufacture Including at least one tangible medium having an 
enterprise directory configured for IF telephony embodied thereon, the article of 
manufacture comprising: 

an X,5G0 compatible enterprise directory embodied on the at least one 
tangible medium, wherein the XJOQ-eomp&tihle enterprise directory is a directory of 
named objects, including users, network devices and network services; 

wherei n a schema of the ente rprise directory includes at least one o bject for 
representing a component of an IP telephony system, the component selected from a 
group consisting of: a GateKeeper; a Gateway; a Multipoint Control Unit (MCU); a 
GateKeeper Exchange: and a user w ith associated telephony service attributes. 

21. A communication system comprising: 

a public switched telephone (PST) network; an internet protocol (IF) network; 
a plurality of gateway networks coupled to the PST network and the IP network, each 
of the plurality of gateway networks con figured to route a telephone call o v er the PST 
network or the IP network; and an enterprise directory server coupled to the plurality 
of gateway networks, the enterprise directory server comprising an enterprise 
directory that is a directory of named objects* Including users, network devices and 
network services and having an extensible schema configured to provide data to 
support muting of telephone calls, 

22. A communication system according to claim 2.1 wherein each of the plurality 
of gateway networks comprise a gateway database capable of providing information 
for routing the telephone call aver the TP network, and wherein the gateway database 
is created from information dredged from the enterprise directory. 

23. A communication system according to claim 22 wherein the enterprise 
directory server is coupled to the IP network, and wherein users of the 
communication system can make changes to objects in the enterprise directory 
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representing components of the communication system through a web browser 
coupled to the I P network, 

24 A communication system according to elako 22 configured to automatically 
update the gateway databases to reflect changes m the enterprise directory. 

25* A communication system according to claim 22 configured to update the 
gateway databases when anew gateway network is added to the communication 
system and information for the new gateway network entered in the enterprise 
directory server, 

26, A communication system according to claim 25 configured to update a 
gateway database associated with one of the plurality of gateway networks when the 
gateway network is placed in operation. 

27, A communication system according to claim 21 wherein the enterprise 
directory comprises in its extensible schema at least one object selected from a group 
consisting of: an object configured to represent a GateKeeper; an object configured to 
represent a Gateway; an object configured to represent a Multipoint Control Unit; an 
object configured to represent a GateKeeper Exchange; and an object configured to 
represent communication system user with associated telephony services attributes. 

29. A communication system according to claim 21 wherein the telephones 
comprise IP telephones, 

30. A communication system according to claim 29 wherein the IF telephones 
include 11323 compliant telephones, 

31. A communication system according to claim 21 wherein the telephones 
comprise non-U 5 telephones including at least one telephone selected from the group 
consisting of: private branch exchange telephones; and plain old telephones (POTS), 
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32. A method of operating a communication system having a plurality of gateway 
networks coupled to an internet protocol (IP) network and to a public switched 
telephone (PS T) network to route a telephone call over the IP network, the method 
comprising steps of: 

providing a directory server comprising an enterprise directory that is a 
directory of named objects, including users, network devices and network services 
and having an extensible schema configured to provide data to support routing of 
telephone calls; 

accessing the directory server, including accessing the extensible schema of 
the enterprise directory, to create a plurality of gateway databases, each 
gateway database associated with one of the plurality of gateway networks 
and each gateway database comprising a list of telephone numbers that each 
of the plurality of gateway networks will accept; 

connecting a user to one of the plurality of gateway networks via a calli ng 
telephone; 

accepting a telephone number entered by the user; accessing the gateway 
database associated with the gateway network to determine which of the plurality of 
gateway networks will accept the telephone number entered by the user; and 

routing the telephone call from the calling telephone over the IP network. 

33. A method according to claim 32 wherein the step of providing a directory 
server comprises the steps of: 

coupling the enterprise directory having the extensible schema to the IP 
network, wherein the schema of the enterprise directory is extended with objects 
representing components of the communication system to create the directory server, 

34. A method according to claim 32 wherein the step of providing a directory 
server comprises the steps of: designating one of the plurality of gateway databases as 
a master database; designating the remaining gateway databases as slave databases; 
and creating within a schema of the master database objects representing components 
of the communication system to create the directory server. 



Atty, Docket No.: DKTRP002 



Page 25 



Appln.No.: 10/086,262 



35, A method according to claim 32 wherein the step of providing a directory 
server further comprises the steps of: accessing a company database coupled to the IP 
network; and copying the company database to a master database* 

36. A method according to claim 32 comprising the further step of accessing the 
enterprise directory server to provide a company white pages comprising lists of users 
and telephone numbers. 

37, A method according to claim 36, wherein the step of providing a company 
white pages comprises the step of providing company white pages in which the 
telephone numbers depend on a location from which the company white pages is 
accessed. 

38. (Currently Amended} A communication system comprising: 
a public switched telephone (PST) network; 

an internet protocol (IP) network; 

a plurality of voice gateways coupled to the PST network and the IP network, 
each of the plurality of voice gateways configured to route a telephone call over the 
PST network or the IP network; and 

general purpose enterprise directory services comprising a distributed network 
of directory servers coupled to the plurality of voice gateways, the directory services 
comprising an enterprise directory that is a directory of named objects, including 
users, network devices and network services and having an extensible schema 
configured to provide data to support routing of telephone calk and configured to 
provide data to support routing of telephone calls over the IP network including 
having an extensible schema including at least one IP telephony object selected from 
a group consisting of: 

an object configured to represent a GateKeeper; an object configured 
to represent a Gateway: 

an object configured to represent a Multipoint Control Unit; an object 
configured to represent a GateKeeper Exchange; and 
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an object configured to represent communication system user with 
associated IP telephony services attributes, 

whereby a single point of entry is provided for making additions, changes and 
deletions of the IP telephony objects by making additions, changes and deletions in 
the schema of the enterprise directory services. 
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10. EVIDENCE APPENDIX 

[37 CPR4i.37(c)(i)(kjj 



Appendices A and B are attached herein below. 
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1* introduction to slapd and siurpd 



This document describes how to build, configure, and run the stand-alone LDAP 
daemon (slapd) and the stand-alone LDAP update replication daemon (siurpd). It is 
intended for newcomers and experienced administrators alike, This section provides 
a basic introduction to directory service, and the directory service provided by slapd 
in particular, 

1.1 What is a directory service? 

A directory is like a database, but tends to contain more descriptive, attribute-based 
information. The information in a directory is generally read much more often than 
it is written. As a consequence, directories don't usually implement the complicated 
transaction or roil-back schemes regular databases use for doing high-volume 
complex updates. Directory updates are typically simple aii-or-nothing changes, if 
they are allowed at all Directories are tuned to give quick-response to high-volume 
lookup or search operations. They may have the ability to replicate infooiiatkm 
widely in order to increase availability and reliability, while reducing response time, 
When directory information is replicated, temporary inconsistencies between the 
replicas may be OK, as Song as they get in sync eventually. 

There are many different ways to provide a directory sen-ice. Different methods 
allow different kinds of information to be stored in the directory, place different 
requirements on how that information can he referenced, queried and updated, how 
it is protected from unauthorized access, etc. Some directory services are local, 
providing service to a restricted context (e.g., the finger service on a single 
machine)* Other services are global, providing service to a much broader context 
(e.g., the entire Internet), Global services are usually distributed, meaning that the 
data they contain is spread across many machines, all of which cooperate to provide 
the directory service. Typically a global service defines a uniform namespace which 
gi ves the same view of the data no matter where you are in relation to the data itself 

1.2 What is LDAP? 

Slupcfs model for directory service is based on a global directory model called 
LDAP, which stands for the lightweight Directory Access Protocol LDAP is a 
directory service protocol that runs over TCP/IP* The nitty-gritty details of LDAP 
are defined in RFC 1777 " The Lightweight Directory Access Protocol" This 
section gives an overview of LD AP from a user's perspective. 

What kind of information can he stored in the directory? The LDAP directory 
service model is based on entries. An entry is a collection of attributes thai has a 
name, called a distinguished name (DN)« The DN is used to refer to the entry 
unambiguously. Each of the entry's attributes has a type and one or more values. 
The types are typically mnemonic strings, like "cn" for common name, or "mail" 
for email address. The values depend on what type of attribute it is. For example, a 
mail attribute might contain the value "babs@umxch.edu". A jpegPhoto 
attribute would contain a photograph in binary JPEG/JFIF format. 

How is the information arranged? In LDAP, directory entries are arranged in a 
hierarchical tree-like structure that reflects political, geographic and/or 

Page 41 



6 



organizational boundaries. Entries representing countries appear at the top of the 
tree. Below them are entries representing states or national organizations* Below 
them might he entries representing people, organizational units, printers, 
documents, or jusi about anything else you can think of Figure i shows an 
example LOAF directory tree, which should help make things clear. 




Figure I: An example LDAP directory tree. 

in addition, LDAP allows you to control which attributes are required and allowed 
in an entry through the use of a special attribute called ofo j ect class. The values 
of the obj ect class attribute determine the schema rules the entry must obey. 

How fa the information referenced? An entry is referenced by its distinguished 
name, which is constructed by taking the name of the entry itself (called the relative 
distinguished name, or RDN) and concatenating the names of its ancestor entries. 
For example, the entry for Barbara Jensen in the example above has an RDN of 
"cn-Baxbara J Jensen" and a DN of "cn= Barbara J Jensen , o~U 
of M, c-US u . The M DN format is described in RFC 1779, "A String 
Representation o f Distingui shed Names /* 

How is the information accessed? LDAP defines operations for interrogating and 
updating the directory; Operations are provided for adding and deleting an entry 
from the directory, changing an existing entry, and changing the name of an entry. 
Most of the time* though, LDAP is used to search for information in the directory , 
t he L DAP search operation al lows some portion of the directory to be searched for 
entries that match some criteria specified by a search filter. Information can be 
requested from each entry that matches the criteria. 

For example, yon might want to search the entire directory subtree below the 
University of Michigan for people with the name Barbara Jensen, retrieving the 
email address of each entry found. LDAP lets you do this easily. Or you might 
want to search, the entries directly below the c-US entry for organizations with the 
string "Acme" m their name, and that have a lax number. LDAP Sets you do this 
too. The next section describes in more detail what you can do with LDAP and how 
it might be useful to you. 

How is the information protected from unauthorized access? Some directory 
services provide no protection, allowing anyone to see the information, LDAP 
provides a method for a client to wt^^ieate, or prove its identity to a directory 
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server, paving the way for rich access control to protect the information the server 
contains, 

1.3 How does LDAP work? 

LDAP directory service is based on a die nf -server model, One or more LDAP 
servers contain the data making up the LDAP directory tree. An LDAP client 
connects to an LDAP server and asks it a question. The server responds with the 
answer, or with a pointer to where the client can get more information (typically, 
another LDAP server). No matter which LDAP server a client connects to, it sees 
the same view of die directory ; a name presented to one LDAP server references the 
same entry it would at another LDAP server. This is an important feature of a global 
directory service, like LDAP, 

1.4 What is slapd and what can it do? 

Slapd is an LDAP directory server that runs on many different UNIX platforms, 
You can use it to provide a directory service of your very own, Your directory can 
contain pretty much anything you want to put in it. You can connect It to the global 
LDAP directory service, or run a service all by yourself* Some of slapdfs more 
interesting features and capabilities include; 

Choke of databases: Skqid comes with three different baekend databases you 
can choose from. They are LDBIvL a high-performance disk-based database; 
SHELL, a database interface to arbitrary UNIX commands or shell scripts; and 
PASSWD, a simple password file database. 

Multiple database instances: Slapd cm be configured to serve multiple 
databases at the same time. This means that a single slapd server can respond to 
requests for many logically different portions of the LDAP tree, using the same or 
different baekend databases. 

Generic database API: If you require even more customization, .slapd lets you 
write your own baekend database easily, Slapd consists of two distinct parts: a 
front end that handles protocol communication with LDAP clients: and a baekend 
tha t handles database operations. Because these two pieces communicate via a well- 
defined C APL you can write your own customized database baekend to slapd. 

Access control: Slapd provides a rich and powerful access control facility, 
allowing you to control access to the information in your databases). You can 
control access to entries based on LDAP authentication information, IP address, 
domain name and other criteria. 

Threads: Slapd is threaded for high performance. A single multi-threaded slapd 
process handles all incoming requests, reducing the amount of system overhead 
required. Slapd will automatically select the best thread support for your platform, 

Replication: Slapd can be configured to maintain replica copies of its database. 
This master/slave replication scheme is vital in high-volume environments where a 
single slapd just doesn't provide the necessary availability or reliability, 
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Configuration: Slapd is highly configurable through a single configuration file 
which allows you to change just about everything you'd ever want to change. 
Configuration options have reasonable defaults, making your job much easier, 

Slapd also has its limitations, of course, it does not currently handle ali ases, which 
are part of the LDAP model The main LDBM database baekend does not handle 
range queries or negation queries very well These features and more will he 
coming in a future release. 

1.5 What about X.500? 

LDAP was originally developed as a front end to X.500, the OS!' directory service, 
X,500 defines the Directory Access Protocol (DAP) for clients to use when 
contacting directory servers, DAP Is a heavyweight protocol that runs over a full 
OSI stack and requires a significant amount of computing resources to run. LDAP 
runs directly over TCP and provides most of the functionality of DAP at a much 
lower cost. 

This use of LDAP makes it easy to access the X,500 directory , but still requires a 
full X.500 service to make data available to the many LDAP clients being 
developed. As with full X.500 DAP clients, a foil X.500 server is no small piece of 
software to run. 

The stand-alone LDAP daemon, or slapd, is nieant to remove much of the burden 
from the server side just as LDAP itself removed much of the burden from clients. 
If you are already running an X.500 service and you want to continue to do so, you 
can probably stop reading this guide, which is all about running LDAP via slapd, 
without running X.500. If you are not running X.500, want to stop running 
X.500, or have no immediate plans to run X,500/read on. 

It is possible to implicate data from a slapd director}' server to an X.500 DSA, 
which allows your organization to make your data available as part of the global 
X*500 directory service on a "readonly" basis. This is discussed in section 1 1 ,6. 

Another way to make data in a slapd server available to the X.500 community 
would be by using a X.500 DAP to LDAP gateway; At this time, no such software 
has been written (to the best of our knowledge), but hopefully some group will see 
fit towrite such a gateway; 

1.6 What is slurpd and what can it do? 

Slurpd is a UNIX daemon that helps slapd provide replicated service. It is 
responsible for distributing changes made to the master slapd database out to the 
various slapd replicas. I t frees slapd front having to worry that some replicas might 
be down or unreachable when a change conies through; slurpd handles retrying 
failed requests automatically, Slapd and slurpd communicate through a simple text 
file that is used to log changes. 
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A Quick-Start Guide to Running slapd 

This section provides a quick step-hy~step guide to building, installing and running 
slapd. It is intended to proYj.de users with, a simple and quick way to get started 
only. If you intern! to run slapd seriously, you should read the rest of this guide. 

J , Get the software. Slapd is part of the LDAP distribution, which y ou can 
retrieve using this URL: 

ftp : / /terminator . rs . ltd . umich , edu/ldap/ldap . tar . Z 

I f you are reading this guide, you ha ve probably already done this. 

2. Itatar the distribution. Pick a place for the LDAP source to live, cd 
there, and imiar it. For example: 

cd /us r/ local / sre 

z ca t. 1 dap + 1 ar . 2 | t ar xvf » 

3. Configure the software. You will have to edit two files to configure 
things for your site, 

vi Make ^common 

vi include/ldapeonf ig . h . edit 

Read the comments in Make -common and configure things appropriately. 
If you have the Berkeley DB package installed, or the GDBM package, you 
should set the LDBMB.ACKEND variable accordingly. Otherwise, the defaults 
should be OK to get you started. 

In the include/ldapeonf ig„h. edit file, be sure to set the 
DEFAULTJ3ASE and LDAPKOST variables to something appropriate for 
your site. Other than that, the defaults should work OK. 

4. Make the software. From the top level IDAP source directory, type: 

make 

Examine the output of this command carefully to ensure everything is made 
properly. If this command foils, seek help. 

5. Install the software. From the top level LDAP source directory, type: 

su 

make ins tall 

Examine the output of this command carefully to ensure everything is 
Installed properfy, 

6. Make a configuration file. Create a file called myalapcLconf and 
enter the following lines into it See Section 5 for more details on this file. 

referral Idap : //Idap . i td . umich , sdu 
database Idbm 

suffix "o^<¥OUR 0RGANI2ATI0N>, C»US W 

root dn »cn«<YOUH HAME>, o-<YOUR QRGmiZA?XOH> > c-US 

rootpw secret 

Be sure to replace *<YOUR 0RGANIZATI0N> U with the name of your 
organization and "<YGUR KAME>" with your name, if you are not m the 
US, replace **US" with yq^r t^p-ktMt country code. The rootdn and 
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rootpw lines are only required if Safer you want to easily add or modify 
entries via LDAP, 

7. Create a database. This is a two-step process. Step A is to create a file 
(well call it myldif) containing the entries you want your database to 
contain. Use the following example as a guide, or see Section 73 for more 
details, 

an: o-<YOUR ORGANIZATION, c-US 
o; <YOUR ORGANIZATION > 
objectclass ; organization 

an: cn^<YOUR HAME>, o==<YOUK ORGAN I 2 AT ION > , c~US 

on: <YOUR MAME> 

sn: <YOUR LAST NAME > 

mail: <YOUR EMAIL ADDRESS > 

obj ectclass : person. 

You can include additional entries and attributes in this file if you want, or 
add them later via LDAP. 

Step B is to run this file through a tool, to create the slapd database, 

$ (ETCDIR) /Idif 2ldbm -f myslapd.conf -i myldif 

Where myslapd, coxif is the configuration file you made in step 6, and 
myldif is the file you made in step 7 A above. By default, the database 
files will he created in /usr/tmp. You may specify an alternate directory 
via the directory option in the slapd , conf file. 

8. Start slapd. Because slapd listens on a privileged TCP port number, you 
will need to be root to do this. 

su 

$ (ETCDIR) /slapd -f myslapd.conf 

9. See if it works. You can use any LDAP client to do this, but our example 
uses the 1 daps e arch tool 

Idapsearch ~h 127.0.0*1 'objectclass-* ' 

This command will search for and retrieve every entry in the database. Note 
the use of single quotes around the filter, which prevents the ton being 
interpreted by the shell 

Yon are now ready to add more entries (e.g., using ldapadd(3) or another LDAP 
client), experiment with various configuration options, Backend arrangements, etc. 
Note that by default, the slapd database grants READ access to everybody. So if 
you want to add or modify entries over LOAF, yon will have to hind as the 
rootdn specified in the eonOg file (see Section 5.2,2), or change the default 
access control (see Section 5.3). 

The following sections provide more detailed information on making, installing, 
and running slapd. 
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3. The Big Picture ~ Configuration Choices 

This section gives a brief overview of various LDAP directory conilgunrtions, and 
ho w your L O AF server (either slapd or Idapd) fits in with the rest of the world, 

3<f as a /oca/ service only 

In this configuration, you run a slapd which provides directory service for vow 
local domain only. It does not interact with other directory servers in any way; This 
configuration is shown in Figure 2. 

LDAP 




Figure 2: Local service via slapd configuration* 
Use this configuration if you are just starting out (it's the one the quick- start guide 



for you) or if you want to provide a local service and are not interested in 
connecting to the rest of the world, lis easy to upgrade to another configuration 
later if you want 

$.2 Local service with X.5O0 referrals 

hi this configuration, you run a slo$)d which provides directory service for your 
local domain and an Idapd which provides access to the X.500 world (you don't 
have to run the Idapd yourself y ou can just point to somebody else who does and 
doesn't mind you pointing to their service). This configuration is shown in 
Figure 3. 




Figure 3: Local service via slapd -f XSOO referrals configuration 

Use this configuration if you want to provide local service hut stili want to he 
connected to the rest of the X.500 world. Remember, you don't necessarily have to 
be running the Idapd in this picture; you just need to find one you can point to. 
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3,3 LDAP as a front end to X.SQO 



In this configuration, you run an X.50G service which provides directory service 
for your local domain and gateway nig service to the rest of the X*50G world, LDAP 
clients gain access to the directory through an kfapd which runs at your site. This 
configuration is shown in figure 4. 



LDAP DAP 



LDAP 
client 




Sdapd 




X,500 
server 







Figure 4: Local service via X500 and Ickqid configuration 

Use this configuration if you are already running an X.500 service, Slapd is not 
invol ved in this configuration, so you can probably stop reading this guide, 

3.4 Replicated slapd service 

The slurpd daemon is used to propagate changes from a master slapd to one or 
more slave slapds. An example master-slave configuration is shown in figure 5. 



Replication 
tog 




slave 
slapd 



slave 
slapd 



Figure 5: Master slapd with two slaves replicated with slurpd 

This configuration can he used in conjunction with the first two configurations in 
situations where a single slapd does not provide the required reliability or 
availability. 
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4, Building and Installing siapd & slurpd 



Building and installing siapd requires three simple steps: configuring; making; and 
installing. Hie following sections describe each step in detail If you am reading 
this guide, chances are you have already obtained the software, but just in case, 
here's where you cm get the latest version of the U~M LDAP package, which 
includes ah of the software discussed in this guide: 

ftp : / /terminator > rs , itd « uraich . edu / 1 dap / 1 dap , tar * 2 

There is also an LDAP homepage accessible from the World Wide Weh, This page 
contains the latest LDAP news, release announcements, and pointers to other 
resources. You cars access it at: 

http : //www. umi cfa « edu/-rsug/Idap/ 
4 A Pre-Build Configuration 

Before building siapd* be sure to take a look at the README file in the top level 
directory in the distribution so that you are familiar with the general configuration 
and male process, 

Briefly, you should edit the include /I dapconf ig Ji.edit and Make- 
common files to contain the site-specific configuration your site requires before 
making. The next sections discuss these steps in more detail 

4* L I Editing the Make -common file 

AH of the general Make -common configuration variables (e.g., ETCDIR, 
BINDIR, etc) apply to both siapd and slurpd. There are additional Make-common 
configuration variables that also aficct how siapd and siwpd are built. They are; 

MAKERS LAPD 

This option controls whether siapd and slurpd get built at all You should 
set it to yes, like this: 

MAKE_SLAPD ~ yes 

SLAPD_BACKENDS 

This option controls which siapd hackend databases get built. You should 
set it to one or more of the following: 

~DLDAP_LDBM This is the main backend. It is a high-perfonnance 
disk-based database suitable for handling up to a 
million entries or so. See the LDBMBACEBND and 
LDBMLIB options below. 

~DLDAP_PASSWD This is a simple search-only backend that can be 
pointed at an /etc/passwd file. It is intended 
more as an example than as a real backend. 
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- DLDAP_SHELL This haekend allows the execution of arbitrary 

system admbisirator-defined commands m response 
to LDAP queries, The commands to execute are 
defined in the configuration file. See Appendix B for 
more information on writing shell 'hackend 
programs. 

Example to enable the LDBM ami SHELL hackends only: 

SLAPD_BACKENDS= -DLDA?_LDBM »DLDAP_SHELL 

The default is to build all three hackends. Note that building a backend only 
means that it can be enabled through the configuration file, not that it will 
automatically be enabled. 

LDBMBA.CKEND 

Ibis option should only be defined if you have enabled the LDBM hackend 
as described above. The LDBM hackend relies on a low-level hash or B-tree 
package for its underlying database. This option selects which package it 
will use. The currently supported options in order of preference are; 

~ DLDBM JJSE J3BBTREE 

This option enables the Berkeley DB package htree 
database as the LDBM hackend, You can get this 
package from 

t tp ; / / £ fc p . c s . be r k et 1 ey . s d u I xx c b / 4 bad/ db . t st r , Z 

- DLDBM^USE JDBHASH 

This option enables the Berkeley DB package hash 
database as the LDBM faaekend You can gel this 
package from 

ftp : / /ftp, - : h^rkel^v . edu/ucb; 4hed/dh , tar. . S 

-DLDBM USE GDBM 

This option enables GNU dbm as the LDBM 
backend You can get this package from 

ftp ; / /prep , a:i - rait , ed-u/pub /gnu/v?db«s - 1.7/3, tar , gss 

-DLDBM USE MDBM 

This option enables the standard UNIX ndbm(j) 
package as the LDBM hackend. 1 his package should 
come standard on your UNIX system, man ndbm 
for details. 

Example to enable the Berkeley DB Btree backend: 

LDBMBACKBND^ -DLDBMjaSBJDBBTREE 

The default is -DLDBM_USEJSDBM» since it is the only one available on all 
UNIX systems. NDBM has some serious limitations, though (not thread* 
safe, severe size limits), and you are strongly encouraged to use one of the 
other packages if you can. 

NOTES TO SOLARIS USERS: If you are running under Solaris 2.x 
and linking in an external database package (e.g., db or gdbm) it is very 
important that you compile the package with the -D REENTRANT flag. If 
you do not. bad things wiii happen. 
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If you are using version L85 or earlier of the Berkeley db package, you will 
need to apply the patch found in build/dfo > i . 85 .patch to the db 
source before compiling it. You can do this with a command like this from 
the db source area: 

patch ~p < ldap»source»dir6ctory/build/db*l .85. patch 

LDBMLIB 

This option should only be defined if you have enabled the LDBM backend 
as described above, and the necessary library for the LDBMSACKEND option 
you chose above is not part of the standard C library (Le„ anything other 
than. NDBM). This option specifies the library to link containing the 
package you selected, and optionally, its location. 

Example to link with lifodb , a, contained in /usr/ local/lib: 

LDBMLIB- -L/usr/local/lib -Mb 

THREADS 

This option is normally set automatically in the Make -plat form file, 
based on the platform on which you are building. You do not normally need 
to set it if you warn to use a no.n-de.fau.lt threads package, you can specify 
the appropriate -Dele fine to enable it here, 

THREADS LIB 

This option is normally set automatically in the Make-platform file, based on 
the platform on which you are building. You do not normally need to set it. 
If you have set THREADS to a ncm-de&ult threads package as described 
above, you can specify the appropriate -Ldirectory flag and 
- 1.1 ibname flag needed to link the package here, 

PHONETIC 

This option controls the phonetic algorithm used by slap d when doing 
approximate searches. The default is to use the raeiaphone algorithm. You 
can. have siapd use the soundex algorithm by setting this variable to 
-DSOUNDEX. 

4, 1.2 Editing the incXude/Xdapconf ig . h file 

In addition to setting the LDAPHOST and DEFAULT BASE defines near the top of 
this file, there are some siapd-spQcifxc defines near the bottom of the file you may 
want to change. The defaults should be just fine, unless you have special needs, 

SLAPD_DEFAULT_CONFIGFILE 

This define sets the location of the default dapd configuration file, 
Normaliy, H is set to $ { ETCDIR) /slapd, conf , where ETCDIR comes 
Jjom Make - common. 
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SXAPDJDBFAULTJ3 I ZELIMIT 

Tbis define sets the default sim limit on the number of entries returned from 
a search, This option is configurable via the tailor file, but if you want to 
change the default do it here. 

SLAPD_DEFAULTjriMELIMIT 

This define sets the default time limit for a search. This option is 
configurable via the tailor file, but if you want to change the default, do it 
here, 

SLAPDJP IDF I LE 

This define sets the location of the file to which shpd will write its process 
ID when it starts up. 

SLAPD_AR.GS F I LE 

This define sets the location of the file to which slapd will write its argument 
vector when it starts up, 

SLAPD_MOHITOR_DN 

This define sets die distinguished name used to retrieve monitoring 
information from slapd. See section 7 for more details, 

SLAPD_LDBM_M1N_MAXIDS 

This define is only relevant to the LDBM baekend, It sets the minimum 
number of entry IDs that an index entry will contain before it becomes an 
alilDs entry. See Section 9.1 for more details, 

4.2 Making the Software 

Once you have edited the include / ldapconf ig * h * edi t file and the Make- 
common file (see the top level README file in the distribution), you are ready to 
make the software. From the top level LDAP source directory; type 

make 

You should examine the output of this command carefully to make sure everything 
is built correctly. Note that this command builds the LDAP libraries and associated 
clients as well as shpd and siurpd. 

Note that the LDAP distribution can support making for multiple platforms trom a 
single source tree, If you want to do this, consult the INSTALL file in the top level 
distribution directory, 

4.3 Installing the Software 

Once the software has been properly configured and successfully made, you are 
ready to install it. You will need to have write permission to the installation 
directories you specified in the Make - common file. Typically, the installation is 
done as root. From the top level LDAP source directory, type 
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make install 

You should examine the output of this command carefully to make sure everything 
is installed correctly; Slapd, slurpd, and their configuration files, slapd, con f ? 
slapd , at . eonf, and slapd. oc, conf mil. be installed in the ETCDIR 
directory you specified in the Make -common file. 

This command will install the entire LDAP distribution. If you only want to install 
slapd and slurpd, you could do something l ike this: 

( cd servers/slapd; make install) 
(cd servers/ slurpd; make install} 

NOTE: The installation process installs configuration files as well as binaries, 
Existing configuration files are first moved to a name with a dash appended, 
e.g., slapd, conf is moved to slapd. conf-, If you install things twice, 
however, you can lose your existing configuration files. 
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5. The slapd Configuration File 



Once the software has been built and installed, you are ready to configure it for use 
at your site. All sfapd runtime configuration is accomplished through the 
slapd, conf file, installed in the ETCDIR directory yon specified in the Make- 
common file. An alternate configuration file can be specified via a command-fine 
option to slapd or shtrpd (see Sections 5 and 8, respectively). This section 
descri bes the genera! format of the eonfig file, followed by a detailed description of 
each eonfig file option. 

$>1 Configuration F/te Format 

The slapd. conf file consists of a series of global configuration options that 
apply to slapd as a whole (including all backends), followed by zero or more 
database backend definitions that contain Information specific to a backend instance. 

Global options can be overridden in a backend (for options that appear more than 
once, the last appearance in the slapd. conf file is used). Blank fines and 
comment lines beginning with a *#* character are ignored, if a line begins with 
white space, it is considered a continuation of the previous line. The general format 
of a lapd , conf is as follows: 

# comment - these options apply to every database 
< g 1 otaal conf ig opt ions > 

# first database definition & eonfig options 
database <backend 1 type* 

< eonfig options specific to backend 1> 

# second database definition & eonfig options 
database < backend 2 type> 

< eonfig options specific to backend 2> 

# subsequent database definitions & eonfig options 



Configuration. Sine arguments are separated by white space, if an argument contains 
white space, the argument should be enclosed in double quotes 'like this**. If an 
argument contains a double quote or a backslash character '\\ the character should 
be preceded by a backslash character *\\ 

The distribution contains an example configuration file that will be installed in the 
ETCDIR directory. Also provided are slapd. at .conf. which contains many 
commonly used attribute definitions, and slapd , oc ♦ conf, which contains many 
commonly used object class definitions, 'These files can be included from the 
slapd configuration file (see below). 

5.2 Configuration Fife Options 

This section separates the configuration file options into global and backend- 
specific categories, describing each option and its default value (if any), and giving 
an exam ple of its use. 
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5-2*1 Global Options 



Options described in this section apply to all baekends* unless specifically 
overridden in a backend definition- Option arguments that should be replaced by 
actual text are shown in brackets <>, 



access to <what> [ by <who> <access I evel > ] * 

1 his option grants access (specified by <aceess!eveS>) to a set of entries 
and/or attributes (specified by <\vhat>) by one or more requesters (specified 
by <who>). See Section 5.3 on access control for more details and 
examples, 

attribute <aame> [<naffie2>] { bin | ces j cis I tel | dn } 

This option associates a syntax with an attribute name. By default an 
attribute is assumed to have syntax cis. An optional alternate name can be 
given for an attribute. The possible syntaxes and their meanings are 

bin binary 

ces case exact string (case must match during comparisons) 
cis case ignore string (case is ignored during comparisons) 
tel telephone number string (like cis but blanks and dashes 

are ignored during comparisons) 
dn distinguished name 

default-access { none j compare j search | read j write } 

This option specifies the default access to grant requesters not mate lied by 
any other access line (see Section 53), Note that an access level implies all 
lesser access levels (eg,, write access implies read, search and 
compare). 

Default; 

def aultaecess read 



inc lu.de < f i 1 ename > 

This option specifies that slapd should read additional configuration 
information from the given file before continuing with the next line of the 
current file, The included file should follow the normal siapci config file 
format* 

Note: You should be careful when using this option - there is no small limit 
on the number of nested include options, and no loop detection is done. 



1 og 1 eve 1 < i n t e ge r > 

This option specifies the level at which debugging statements and operation 
statistics should be sy slogged (euiTentiy logged to the sydogd(8) 
L0G_LOCAL4 facility). You must have compiled slapd with 
-DLDAPJDEBUG for this to work (except for the two stats levels, which are 
always enabled). Log levels are additive. To display what numbers 
correspond to what kind of debugging, invoke slapd with the - ? flag or 
consult the table below. The possible values for <integer> are; 
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1 trace function calls 

2 debug packet, handling 
4 heavy trace debugging 
8 connection management 

16 print out packets sent and received 

32 search filter processing 

64 configuration file processing 

128 access control list processing 

256 stats log connections/operations/results 

5 1 2 s t a t s 1 og ent ri e s sent 

1024 print communication with shell backands 

204 8 print entry parsing debugging 

Example: 

log level 255 

This will cause lots and lots of debugging information to be sy slogged. 

Defeuit: 

log level. 256 

object class < name > 

[ requires <attrs> 1 
[ allows <attrs> 3 

This option defines the schema rules for the given object class, Used in 
conjunction with the schemacheck, option. See Section 5.4 for more 
details. 

referral <url> 

This option specifies the referral to pass hack when slapdcmmoi find a local 
database to handle a request 

Example: 

ref er ra 1 ldap : / /I dap , i t d , umi ch . edu 

This will refer non-local queries to the LDAP server at the University of 
Michigan. Smart LDAP clients can re-ask their query at iliat server, but note 
that most of these clients are only going to know how to handle simple 
LDAP URLs that contain a host part and optionally a distinguished name 
part 

schemacheck { on j off } 

This option turns schema checking on or ofE If schema checking is on, 
entries added or modified will be checked to ensure they obey the schema 
rules implied by their object class(es) as defined by the corresponding 
object class optkm(s), If schema checking is off this check is not done. 

Default: 

schemacheck off 
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sxzelimit <irxteger> 

This option specifies the maximum number of entries to return from a 
search operation. 

Default 

size limit 500 

s rvt ab < f i lename > 

This option specifies the srvtab fife in which slapd cm find the kerberos 
keys necessary for authenticating clients using kerberos. This option is only 
meaningful if you are using kerberos authentication, which must be enabled 
at compile time by including the appropriate definitions in the Make - 
common file. 

Default: 

s rvt afa / e t c/s rvt ab 

time limit <integer> 

This option specifies the maximum number of seconds (in real time) slapd 
will spend answering a search request. If a request is not finished in this 
time, a result indicating an exceeded tinieJimii will be returned* 

time limit 3600 
5/2*2 General Backend Options 

Options in this section only appiy to the backend in which they are defined, They 
are supported by every type of backend. 

dat aba se < da t aba s etype > 

This option marks the beginning of a new database instance definition. 
<dat abase type > should be one of Idbm, shell, or passwd, 
depending on which backend will serve the database. 

Example: 

database 1 dfora 

This marks the beginning of a new IX>BM backend database instance 
definition. 

lastmod { on | off } 

This option controls whether slapd will automatically maintain the 
mod i f iersName, modi f yTimes t amp, creatorsName* and 
cr eat eTime s t amp attributes for entries, 

Defeuh: 

lastmod off 

Page 57 



22 



readonly {on j off } 

This option puis the database into *Vead-only w mode. Any attempts to 
modify the database will return an ^unwillmg to perform" error, 

Defeuit: 

readonly off 

replica host ^< host name > [ : <port>] 
"fainddn^<DN>" 

bindmethod™ { simple j kerberos } 
[ credent ials^<password>] 
[ s rv t afo- < f i 1 ename > 3 

This option specifies a replication site for this database. The host- 
parameter specifics a host and optionally a port where the slave slapd 
instance can be found. Either a domain name or IP address may he used for 
<hostname>. If <port> is not given, the standard LD/VP port number 
(389) is used. 

The binddn- parameter gives the DN to hind as for updates to the slave 
slapd. li should be a DN which has read/ write access to the slave slapd \s 
database, typically given as a "rootdrf" in the slave* s eonfig file, ft must 
also match the updatedn option in the slave slapds config file. Since 
DNs are likely to contain embedded spaces, the entire "binddn*<DN> M 
string should be enclosed in quotes. 

bindmethod is either simple or kerberos, depending on whether 
simple password-based authentication or kerberos authentication is to be 
used when connecting to the slave slapd Simple authentication requires a 
valid password be given, Kerberos authentication requires a valid srvtab 
trie. 

The credentials- parameter, which is only required if using simple 
authentication, gives the password for binddn on the slave slapd. 

The srvtab« parameter, which is only required if using kerberos, 
specifies the filename which holds the kerberos key for the slave slapd if 
omitted, /etc /srvtab is used. 

See Section 1 0 for more details on replication, 

repiogfile <filename> 

This option specifies the name of the replication log file to which slapd will 
log changes. The replication log is typically written by slapd and read by 
slurpit Normally, this option is only used if slwpd is being used to 
replicate the database. However, you can also use it to generate a 
transaction log, if slurjid is not running. In this case, you will need to 
periodically truncate the file, since it will grow indefinitely otherwise. 

See Section 10 for more details on replication, 

rootdn <dn> 

This option specifies the DN of an entry that is not subject to access control 
or administrative limit restrictions for operations on this database. 
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Example: 

rootdn "cn -Manager, o=U of M , c=US" 

rootkrbname <kerberosnarae> 

This option specifies a fcetberas name for the DN given above that will 
always work, regardless of whether an entry with the given DN exists or 
has a krbName attribute. This option is useftii when creating a database and 
also when using slwpd to provide replication service (see Section 10). 

Example: 

rootkrbname admin#umich * edu 

root pw <pas sword > 

This option specifies a password for the DN given above that wilt always 
work, regardless of whether an entry with the given DN exists or has a 
password. This option is useful when creating a database and also when 
using siurpd to provide replication service (see Section 10), 

Example: 

rootpw secret 

suffix <dn suf f ix> 

This option specifies the DN suffix of queries that will be passed to this 
backend database. Multiple suffix tines can be given, and at least one is 
required for each database definition. 

Example: 

suffix "o-University of Michigan, c»US H 

Queries with a DN ending in ^o^University of Michigan, c^US" 
will he passed to this backend, 

Note: when the backend to pass a query to is selected, sktpd looks at the 
suffix Hne(s) in each database definition in the order they appear in the file, 
Thus, if one database suffix is a prefix of another, it must appear after it in 
the eonfig file, 

updatedn <dn> 

This option is only applicable in a slave siapd li specifies the DN allowed 
to make changes to the replica {typically, this is the DN siurpd binds as 
when making changes to the replica). 

5*2.3 LDBM Baekemi-Specitic Options 

Options in this category only apply to the LDBM backend database, That is, they 
must follow a "database Idhrrr line and come before amy other "database" 
line. 

caches! ze < integer > 

1 his option specifies the size in entries of the in-memory cache maintained 
hv the LDBM backend database instance. 
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Default 

caches ize 1000 

db c a c h e s i z e <integer> 

This option specifies the size In bytes of the m-memory cache associated 
with each open index file. If not supported by the underlying database 
method, this option is ignored without comment, 1'ncreastng this number 
uses more memory but can cause a dramatic performance increase, 
especially during modifies or when building indexes. 

Defeuit: 

dbcache size 10 0000 

directory <dIrectory> 

This option specifies the directory where the LDBM fiies containing the 
database and associated indexes live. 

Defeuit: 

directory /usr/tmp 

index (<attrlist> [ default} [pres, eq.approx, sub, none] 

This option specifies the indexes to maintain for the given attribute, if only 
an <attrli st> is given, all possible indexes are niainiained. 

Example: 

index cn 

index sn, uid eq, sub, approx 

i ndex de fault none 

This example causes ail indexes to be maintained for the en attribute; 
equality, substring, and approximate indexes for die sn and uid attributes; 
and no indexes for all other attributes. 

mode < i nt eger > 

This option specifies the file protection mode that newly o^cmd database 
index files should have. 

Default: 

mode 0600 
5*2*4 Shell Backend-Specific Options 

bind <pat hname > 

unbind < pathname > 

search <pat hname > 

ompare <pa thname > 



modi f y <pat hname > 

modr dn < pathname > 

add <pat hname > 

delete <pa thname > 

abandon <pa t hname > page 60 
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These options specify the pathname of the command to execute in response 
io the given LDAP operation. The command given should understand and 
follow the input/output conventions described In Appendix B. 

Example; 

search / usr /.local /bin/ search* sh 

Note that you need only supply those commands you want the haefcend to 
handle. Operations for which a command is not supplied will be refused 
with m i4 iittwiiiing to perform" error. 

5*2*5 Password Bacfceiid«Spectiic Options 

Options in this category only apply to the PASS WD baekend database. That is, they 
must follow a "database passweT line and come before any other 
"database" fine, 

file <£ilename> 

This option specifies an alternate passwd file to use. 
Default: 

file /etc /pas a wd 
$,3 Access Control 

Access to siapci entries and attributes is controlled by the access configuration file 
directive. The general form of an access line is: 

^access directive;* : : - access to <what> 

[ by <wfro> <access> j + 
< wha t > : : ~ * j t dn ~ < r eg ex> 1 [ f ilt:er~<l dap f liter > ] 

f at t:rs^<att rlist> ] 
<who> ■ * j self j dn=<rege%> \ addr=<regex> j 

do*nain»<regsx> j dnattr~<dn attribute > 
<access> : i = [self 3 none \ [self 1 compare j [self 3 search 

| [self ] read j [self] write 

where the <what> pari selects the entries and/or attributes to which the access 
applies, the <who> pari specifies which entities are granted access, and the 
<accesB> part specifies the access granted. Multiple <who> <a.ccess> pairs 
are supported, allowing many entities to he granted different access to the same set 
of entries and attributes. 

5*3,1 What to control access to 

The <what> part of an access specification determines the entries and attributes to 
which the access control applies. Entries can be selected in two ways: by a regular 
expression matching the entry's distinguished name: 

dn~<regular expression^ 

NOTE: The ON pattern specified should he "normalized", meaning thai there 
should he no extra spaces, and conjajp%f hould he used to separate components* An 
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example normalized DN is "cn~Babs Jensen / ©-University of 
Michigan, c~US", An example of a nonHrcorroaUzed DN is "cn -Batas 
Jensen; o-Universxty of Michigan, c~US'\ 

Or. entries may be selected by a filter matching some attrihute(s) in the entry : 

£ilter~<ldap f liter > 

where <ldap f liter > is a string representation of an LDAP search filter, as 
described in RFC 1588. The special entry selector "* w is used to select any entry, 
and Is a convenient shorthand for the equivalent w dn= . selector. 

Attributes within an entry are selected by including a comma-separated list of 
attribute names in the <what> selector: 

attrss*<at tribute list > 

Access to the entry itself must be granted or denied using the special attribute name 
"entry". Note that giving access to an attribute is not enough: access to the entry 
itself through the "entry 61 attribute is also required. The complete examples at the 
end of this section should help clear things up, 

5.3*2 Who to grant access to 

The <who> part identifies the entity or entities being granted access, Note that 
access is granted to "entities" not "entries/* Entities can be specified by the special 
identifier, matching any entry, the keyword "self' matching the entry 
protected by the access, or by a regular expression matching an entry's 
distinguished name: 

dn~ < r egul a r expr e s s ion > 

NOTE: The DN pattern specified should be "normalized", meaning that there 
should be no extra spaces, and commas should be used to separate components. 

Or entities can be specified by a regular expression matching the client's IP address 
or domain name: 

addr « < r egul ar expr e s s i on> 
domain- < regular expression 

or by an entry listed in a DN-valued attribute in the entry to which the access 
applies: 

dnattr«<dn-*valued attribute name> 

The dnattr specification is used to give access to an entry whose DN is listed in 
an attribute of the entry (e.g., give access to a group entry to whoever is listed as 
the owner of the group entry ). 
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5-3*3 The access to grant 



The kind of < access > granted can be one of the following: 

none j compare j search j read j write 

Note that each level implies all lower levels of access. So, for example, granting 
someone write access to an entry also grants ihem read, search, and 
compare access, 

5*3.4 Access Control Evaluation 

When evaluating whether same requester should be given access to an entry and/or 
attribute, siapd compares the entry and/or attribute to the <what> selectors given in 
the configuration file. Access directives local to the current database are examined 
first, followed by giobal access directives. Within this priority, access directives are 
examined in the order in which they appear in the config file. Siapd stops with the 
first <what> selector that matches the catty and/or attribute. The corresponding 
access directive is the one siapd will use to evaluate access, 

Next^ siapd compares the entity requesting access to the < who selectors within the 
access directive selected above, in the order in which they appear. It stops with the 
first <who> selector that matches the requester. This determines the access the 
entity requesting access has to the entry and or attribute. 

Finally, siapd compares the access granted in the selected <access> clause to the 
access requested by the client, If it allows greater or equal access, access is granted. 
Otherwise* access is denied. 

The order of evaluation of access directives makes their placement in the 
configuration file important if one access directive is more specific than another in 
terms of the entries it selects, it should appear first in the config file. Similarly, if 
one <who> selector is more specific than another it should come first in the access 
directive. The access control examples given below should help make this clear. 

5*3*5 Access Control Examples 

The access control fecility described above is quite powerful This section shows 
some examples of its use' First, some simple examples; 

access to * by * read 

This access directive grants read access to everyone. If it appears alone it is the 
same as the following clef aultaccess line. 

def aultaccess read 

The following example shows the use of a regular expression to select the entries 
by DN in two access directi ves where ordering is significant. 

access to dn« u v * , o*U of M, c-US " 
by * search p 63 
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access to dn~* c-US" 
by * read 

Read access is granted to entries under the c~0S subtree* except for those entries 
under the '^University of Michigan, c~US'- subtree, to which search 
access is granted* I f the order of these access directives was reversed, the U-M~ 
specific directive wrmld never be matched, since ail IhM entries are also c*US 
entries. 

The next example again shows the importance of ordering, both of die access 
directives and the w by^ clauses. It also shows the use of an attribute selector to 
grant access to a specific attribute and various <who> selectors. 

access to dn~" . *, g~U of M, c~US" at tr= home Phone 

by self write 

by dn~ " . * , o~U of M, c=US H search 

by domain- * * V umich\ w edu read 

by * compare 

access to dn« fi o«U of M, c-US" 

by s e 1 f wr i t e 

by dn«" o~U of M, c~US" search 

by * none 

This example applies to entries in the "o=*U of M, c~US w subtree, To all 
attributes except home Phone, the entry itself can write them, other U-M entries 
can search by them, anybody else has no access. The homePhone attribute is 
writable by the entry, searchable by other U-M entries, readable by clients 
connecting from somewhere in the umich.edu domain, and comparable by 
everybody eke. 

Sometimes it is useful to permit a particular DN to add or remove itself from an 
attribute. For example, i f you would like to create a group and allow people too add 
and remove only their own DN from the member attribute, you could accomplish it 
with an access directive Mke this: 

access to at t remember , entry 

by dnattr-member self write 

The dnattr <vmo> selector says that the access applies to entries listed in the 
member attribute. The self write access selector says that such members can 
only add or delete their own DN from the attribute, not other values. The addition 
of the entry attribute is required because access to the entry is required to access 
any of the entry -s attributes. 

Note that the a tt remember construct in the <what > clause is a shorthand for the 
clause "dn~* at t remember" (he., it matches the member attribute in all 
entries), 

5,4 Schema Enforcement 

The object class and schemaehsek configuration file options can be used to 
enforce schema rules on entries in^p ^rectory, The schema rules are defined by 
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one or more obj ectclass lines, and enforcement is turned on or off via the 
schema check option. The format of an obj ectclass line is: 

oh j ect class <name> 

[ requires <attrs> j 
[ al lows <attrs> ] 

This option defines the schema rules for the object class given by <naroe>. Schema 
rules consist of the attributes the entry is required to have (given by the requires 
<attrs> clause) and those attributes that it may optionally have (given by the 
allows <attrs> clause). In both clauses, <attrs> is a comma-separated list 
of attribute names, 

Note that object class inheritance (that is, defining one object class in terms of 
another) is not supported directly. All of an object ciass*s required and allowed 
attributes must be listed in the obj ectclass definition, 

For example, to define an objectclass called oiyPerson, you might include a 
definition like this: 

objectclass myperson 

re qui re a cn , sn f obj act class 
allows mail , phone , fax 

TV) then enforce this rule (Le„ to make sure an entry with an objectclass of 
myperson contains the cn, sn and ob j ectclass attributes, and thai it contains 
no other attributes besides mai 1, phone, and fax), turn on schema checking with 
a line like this: 

s chemacheek on 

5.5 Configuration Fii& Example 

The following is an example configuration file, interspersed with explanatory text. 
It defines two databases to handle different parts of the X.500 tree; both are LDBM 
database instances. The line numbers shown are provided for reference only and are 
not included in the actual file. First the global configuration section: 

!, # example eonfig file ~ global configuration section 

2 , include /usr/local/etc/slapcL at >con£ 

3 , include /usr/Xocal/etc/slapd.oc .corif 

4 , s chemacheek on 

5 , referral ldap://ldap » ltd, umich.edu 

line 1 is a comment. Lines 2 and 3 include other eonfig files containing attribute 
and object class definitions, respectively. Line 4 turns on schema checking. The 
referral option on line 5 means that queries not I oca! to one of the databases 
defined below will be referred to the LDAP server running on the standard port 
{389) at the host Idap ♦ ltd. umxch * adu. 

The next section of the configuration file defines an LDBM baekend that will handle 
queries for things in the ^o-tlni varsity of Michigan , c~0S* ? portion of 
the tree. The database is to be rep&@§&si to two slave dapds, one on truelies* 
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the other on judgment day. indexes are to be maintained for several attributes, 
and the user Pas sword attribute is to be protected from unauthorized access. 



1, # Idhra definition for the U-M database 

2 , database Idbm 

3, suffix "owUniversity of Michigan, c-US" 

4 , directory /usr/local/ldbm-umich 

6, rootdn " en ^Manage r, o-University of Michigan, c*US M 

7, rootpw secx~et 

8 , replogf ile /uer/local/ldbm-iaaich/slapd. replog 

9 , replica host^truelies. rs , ltd . umich * edu ; 3 8 9 

10, binddn«* en- Replicator, o~U of M, c-US" 
1 1 * fo ixidme t hod= s imp 1 e c re dent lals-sec re t 

12 . replica host** judgment day , rs , ltd , umieh v edu 

13. binddn= * cn^Repl xca tor , o=U of m, c=us w 

1 4 . b indme t hod-kerberos 

15 * srvt&b~/efcc/srvtab * judgmentday 

16. U Idbm indexed attribute definitions 

17 , index cn , sn , uid pres , eq , appro x , sub 

I S . index ob j ect class pres , eq 

1 9 , index de f au 1 1 none 

20. # Idbm access control definitions 

21 . def aixltaccess read 

22* access to attr-userpassword 
23 . by self write 

2 4. . by d n « " cn Adm i n , o ^ On i vers! t y of M i eh i g a n , c « US " i t & 
25, by * compare 

Line 1 is a comment. The start of the database definition is marked by the database 
keyword on line 2. Line 3 specifies the DM suffix for queries to pass to this 
database, line 4 specifies the directory in which the database flies will Ji ve 

Lines 6 and 7 identify the database "'super user" entry and associated password. 
This entry is not subject to access control or size or time limit restrictions. 

lines 8 through 15 are for replication. line 8 specifies the replication log file 
(where changes to the database are logged - this file is written by slapd and read by 
slurpd). lines 9 through 1 1 specify the hostname and port for a replicated host, the 
DN to bind as when performing updates, the bind method (simple) and the 
credentials (password) for the binddm Lines 12 through 15 specify a second 
replication site, using kerberos instead of simple authentication. See Section 10 on 
durpd for more information on these options, 

lines 16 through 19 indicate the indexes to maintain for various attributes. The 
default is not to maintain any indexes (line 1 9), 

Lines 20 through 25 specify access control for entries in the database. For all 
entries, the user Pas sword attribute is writable by the entry and the "admin'' 
entry, comparable by everyone else. Ail other attributes allow read access by default 
(line 21). Note that the special "entry" attribute is not required in the access 
directive beginning on line 22, This is because the default access is read. 

The next section of the example configuration file defines another LDBM database. 
This one handles queries involving the £i o^ "Bafos , Inc , " , e~TJS" subtree. 
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1, £ idbm definition for Sabs, Inc. database 

2 » database Xdbm 

3, suffix H o=A"Babs, Inc,\" , c^US" 

4 , directory /us r/ loca 1 / Xdhm-babs 

5. root dii "cn*Babs, o-V ! Babs, IncA", c-US" 

6. index default 

Note the use of ; V to escape the quotes necessary in the distinguished names given 
on lines 3 and 5, By default, all indexes are maintained for every attribute in m 
entry. 
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6. Running slapd 



Skipdcmi be run in two different modes, stand-alone or from ineid(S). Stand-alone 
operation is recommended, especially if you are using the LDBM backend* This 
allows the Backend to take advantage of caching and avoids concurrency problems 
with the LDBM index files, if you are running only a PASS'WD or SHELL 
backend, running from meld is an option. How to do this is described in the next 
section, after the command-line options and stand-alone daemon operation are 
described. 

6,1 Command-Line Options 

Slapd supports the following command-line options, 

~d < level > | ? 

This option sets the slapd debug level to < level > . When level is a '?* 
character, the various debugging levels are printed and slapd exits, 
regardless of any other options you gi ve it. Current debugging leve ls are 

1 trace function calls 

2 debug packet handling 
4 heavy trace debugging 
8 connec t i on. management 

16 print out packets sent and received 

32 search filter processing 

64 configuration file processing 

128 access control list processing 

256 stats log connections/operations/results 

512 stats log entries sent 

1024 print communication with shell backends 

204 8 print entry parsing debugging 

6553 5 enable all debugging 

Debugging levels are additive, That is, if you want to trace function calls 
and watch the coniki file being, processed, yon would set level to the sum of 
those two levels (in this case, 65), Consult < Idap , h> for more details. 

Note that slapd. must have been compiled with -DLDAPJ3EBUG defined for 
any debugging information beyond the two stats levels to he available, 

-£ <f ilename> 

This option specifies an alternate configuration file for slapd. 

This option tells slapd that it is running from ineid instead of as a stand- 
alone server. See the next section on running slapd. from inetd for more 
details. 

~p <port> 

This option specifies an alternate TCP port on which slapd should listen for 
connections. The default port is 389, 
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6.2 Running slapd as a Stand-Alone Daemon 

In general slapd is run like this: 

$ CETCDIR) /slapd [<option>] * 

where ETCDIR has the value you gave in the Make -common file during the pre- 
build configuration, and < opt ion > is one of the options described below. Unless 
you have specified a debugging level, slapd wM automatically fork and detach itself 
from its controlling temiinai arid run in the background. Any of the options given 
above can be given to slapd to point it at a different configuration file, listen on 
another port, etc. 

To kill off slapd safely , you should give a command like this 
kill - TERM "cat $ (ETCDIR) /slapd. picT 

Killing siapd by a more drastic method may cause its LDBM databases to be 
corrupted, as it may need to flush various buffers before It exits. Note that skqxl 
writes its pid to a file called slapd . pid in the ETCDIR you configured in Make- 
common. You can change the location of this pid file by changing the 
SLAPD^P IDFILE variable in include/ Idapcon fig 4 h> edit. 

Slapd will also write its arguments to a file called slapd* args in the ETCDIR 
you configured in Make - common. You can change the location of the args file by 
changing the SLAPD_AE.GS FILE variable in include/ idapconf ig . h. edi t, 

6.3 Running siapd from in&id 

First, make sure that running irom metd(%) is a good idea. If you are using the 
L DBM hackend, it is not. If you are in a high- volume environment, the overhead of 
running from rnetd also makes it a bad idea. Otherwise, you may proceed with the 
two steps necessary. 

Step 1 is to add a line like this to your /etc /services file: 

1 dap 3 89 #1 dap d x re c t o r y s e r v i c e 

Step 2 is to add a line like this to your /etc/inetd , conf file: 

1 dap stream tcp no wait nobody $ (ETCDIR) /slapd slapd -i 

where ETCDIR has die value you gave it in the Make -common file during pre- 
build configuration. Finally, send imtda. HUP signal and you should be all set. 
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Monitoring Slapd 



Siapd supports a monitoring interface you can use to find out many useful bits of 
information about what siapd is currently doing, how many connections it has, bow 
many threads are working, etc. You can access the monitor feature by doing a base 
object search of the SLAPD MONITOR DN from include / Idapconf ig „ h 
with any kind of valid filter (e.g., rt (object class-* 5 #, )« By default, this DN is 
set to "en-monitor". You will get one entry returned to you, with the following 
attributes: 

version: slapd <version> {<date>} 

Ibis attribute identifies the siapd server software by name, version, and 
build date, e,g,, & lapd 3.3 (Thu May 21 14:19:03 EOT 1996) 

threads : < integer > 

This attribute indicates the number of threads (operations) currently 
outstanding m siapd. 

connection : <£ d> : <opentirae> : <opsinitiated> : 

<opscompleted> ; <binddn> : [ < rw> ] 

This multi-valued attribute summarizes information for each open 
connection. The information given is <£dx the file descriptor; 
<opentime>, the time the connection was opened in UTC format; 
<ops ini t i at ed> , the number of operations initiated over the 
connection; <opscompleted>* the number of operations completed over 
the connection: <biriddn>, the DN currently bound to the connection: and 
optionally <rw>. indicating whether the connection is currently blocked for 
read or write., 

current connect ions : <integer> 
The current number of connections. 

totalconnect ions : < integer > 

1 he total number of connections handled by siapd since it started, 

dtablesize : < integer > 

The size of slapcfs file descriptor table, 

writewaiters ; <integer> 

The number of threads blocked waiting to write data to a client 

read waiters : < integer > 

The number of threads blocked waiting to read data item a client 

opsinitiated : <integer> 

The total number of operations ini tiated by siapd since it started, 
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opscompleted; < integers 

The total number of operations completed by siapd since it started 

entriessent : < integer > 

The total number of entries sent to clients by since it started. 

by t e s sent : < i nt ege r > 

The total number of bytes sent to clients by siapd since it started. 

current time : <UTC bime> 

Slapds idea of the current time. 

s caret ime : < integer > 

The time siapd was started, 

abackencls : <integer> 

The number of backends currently being served by slapd. 

concurrency i <integer> 

Under Solaris 2.x only, an indication of the current level of thread 
concurrency. 

Note thai slapx! takes a snapshot of this information and returns it to you. No 
attempt is made to ensure that the information is consistent (i,e„ if an operation 
thread is modifying one of these things when the monitor thread is reading it, 
strange results could he returned). 

You should be able to use any LDAP client to retrieve this information, Mere's how 
yon might do it using the idapworch(i ) client: 

ldapsearch ~s base -b cn~monitor 1 objectclass=* 1 
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8, Database Creation and Maintenance Tools 



This section tells you how to create a slapd database from scratch, and how to do 
trouble shooting if you run into problems. There are two ways to create a database. 
First, you can create the database on-line using LDAP. With this method, you 
simply start up slapd and add entries using the LDAP client of your choke. This 
method is line for relatively small databases (a few hundred or thousand entries, 
depending on your requirements). 

The second method of database creation is to do It off-line, using the index 
generation tools. This method is best if you have many thousands of entries to 
create, which would take an unaceeptabiy long time using the LDAP method, or if 
you want to ensure the database is not accessed white it is being created. 

8,1 Creating a database over LDAP 

With this method, you use the LDAP client of your choice (e.g., the Idapadd{\) 
too!) to add entries, just like you would once the database is created. You should be 
sure to set the following configuration options before starting slapd: 

suffix <dn> 

As described in the preceding section, this option says what entries are to be held 
by this database. You should set this to the DN of the root of the subtree you are 
trying to create. For example 

suffix "o« University of Michigan, c-US" 
You should be sure to specify a directory where the index files should be created: 

directory < directory > 

For example: 

directory /usr/iocai/umich- slapd 

You need to make it so you can connect to slapd as somebody with permission to 
add entries. This is done through the following two options in the database 
definition: 

rootdn <dn> 
rootpw <passwd> 

These options specify a DN and password that can be used to authenticate as the 
"superuser 5 entry of the database the entry allowed to do anything), Hie DN 
and password specified here will always work, regardless of whether the entry 
named actually exists or has the password given. This solves the chieken-and-egg 
problem of how to authenticate and add entries before any entries yet exist. 

Finally^ you should make sore that the database definition contains the index 
definitions you want: 
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index {<attrlist> j default} [pres, eq, approx, sub, none] 

For example, to index the cn, sn, uid and objectclass attributes the 
following index configuration lines could be used. 

index cn, sn,uid 

index objectclass pres, eq 

1 nd&x d e f a u 1 1 none 

See Section 4 on the configuration file for more details on this option. Once you 
liave configured things to your liking, start up slapd„ connect with your LDAP 
client, and start adding entries, For example, to add a the U of M entry followed by 
a Postmaster entry using the kiapcuid tool, you could create a file called 
/ tmp / newent ry with the contents; 

o» University of Michigan, c:~US 
ob j e c t C 1 a s 3 - o rgan i z a t i on 
o«University of Michigan 

descript ion*Ttaiversity of Michigan at Arm Arbor 

cn« Postmaster , o^Universit.y of Michigan, c«US 
obj«ctClass»or gan i z a t i ona 1 Role 
cn^Pos t ma st e r 

descriptions!? of M postmaster - posttaaster^umich.edu 

and then mc a command like this to actually create the entry : 

Idapadd -f /tmp/n^wantry -D "cn^Manager, o^Univeraity of 
Michigan, c«US" w secret 

The above command assumes that you have set rootdxi to "cn ^Manager, 
a -University of Michigan, c^US'and rootpw to "secret"'. 

5-2 Creating a database ofNine 

The second method of database creation is to do it off-line, using the index 
generation tools described below, This method is best if yon have many thousands 
of entries to create, which would take an imacceptebly long time using the LDAP 
method described above, These tools read the dapd configuration file and an input 
file containing a text representation of the entries to add, They produce the LDBM 
index flies directly, There are several important configuration options you will want 
to be sure and set in the config file database definition first: 

suffix <dn> 

As described in the preceding section, this option says what entries are to be held 
by this database. You should set this to the DN of the root of the subtree you are 
try ing to create. For example 

suffix "o^Uni varsity of Michigan, c~US" 

You should be sure to specify a directory where the index flies should be created: 

directory <directorv>„ 
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For example; 

directory /usr / local /umich- slapd 

Next , you probably want to increase the size of the in -core cache used by each open 
index file. For best performance during index creation, the entire index should fit in 
memory , If your data is too big for this, or your memory too small, you can still 
make it pretty big and let the paging system do the work. This size is set with the 
following option: 

dfocache size < i n t age r > 

For example: 

dbcacheaize 50000000 

This would create a cache 50 MB big, which is pretty big (at U-M, our database has 
about 1.25K entries, and our biggest index file Is about 45 MB). Experiment with, 
this number a bit, and the degree of parallelism (explained below), to see what 
works best for your system, Remember to turn this number back down once your 
index files are created and before you run slapd.. 

Finally, you need to specify which indexes you want to build. This is done by one 
or more index options. 

index { <a 1 1 r l i & t > \ de f au 1 1. } [pres , eq, approx , sub , none J 

For example: 

index en , sn , uid pres f eq, approx 

index default none 

This would create presence, equality and approximate indexes for the en, sn, and 
uid attributes, and no indexes for any other attributes. See the configuration file 
section for more information on this option. 

8*2,1 The UlifZttlbm program 

Once you've configured things to your liking, you create the indexes by running the 
(difildhm program; 

ldif21dbm -i <±nputfile> -f <s!apdconf igf ile> 
[ - d <debu^level > } I - j < int eger> j 
l~n <da t abasenumbe r > ] if-e <etcdir>] 

The arguments have the following meanings: 
-i < input f ile> 

Specifies the LDIF input file containing the entries to add in text form (described 
below in Section 8.3). 

- f <s 1 apdconf igf ile> 
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Specifies the slqpd configuration file that tells where to create the indexes, what 
indexes to create, etc. 

-d < debug 1 eve 1 > 

Turn on debugging, as specified by <debuglevel>. The debug levels are the 
same as for slapd (see Section 6 A )/ 

■»j < integer > 

An optional argument that specifies that at most < int eger > processes should he 
started in parallel when building the indexes. The default is 1. If set to a value 
greater than one, ldi?2Idbm will create at most that many subproeesses at a time 
when building the indexes, A separate subproeess is created to build each attribute 
index. Running these processes in parallel can speed things up greatly, but beware 
of creating too many processes, all competing for memory and disk resources. 

~n < da t a b asenu mb e r > 

An optional argument that specifies the configuration file database for which to 
build indices. The first database listed is 'T\ the second }y 2 l \ etc. By default, the 
first Idfom database in the configuration file is used. 

~e <etcdir> 

An optional argument that specifies the directory where l.dif 2 Idfom can find the 
other database conversion tools it needs to execute (Idif 2 index and friends). 
The default is the installation ETCDIR, 

The next sections describe Hie programs invoked by ldi/2ldhm when it is building 
indexes. Normally; these programs are invoiced for you, but occasionally you may 
want to invoke them yourself, 

8/2,2 The Idiflindex program 

Sooietimes it may be necessary to create a new attribute index file without 
disturbing the rest of the database. This is possible using the Idiflindex program, 
Idif2index is invoked like this 

Id..if2index -i <inputfile> -f olapdconf icjf ile> 

l-d <debuglevel>3 l-n < da t aba s eauiab e r > ] <attr> 

Where the »f „ ~d, and ~n options are the same as for the ldif2ldhm program. 
<attr> is the attribute to build an index for. Which indexes are built (e-g*» 
equality, substring, etc;) is eontrolied by the corresponding index line in the slqpd 
configuration file, 

You can use the Idhmcat program to create a suitable LDIF input file from an 
existing LDBM database. 
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8.2,3 The idlf2id2entry program 

The Idif2id2eniry program is noraiaSiy Invoked from kU0dbm. it is used to 
convert an LDIF text file into an icl2 entry index. It is unlikely thai you would 
need to invoke It yourself but if you do it works like this 

Xdif 2id2entry -i < input f ile> -f <slapdcon£ igf ile> 
[~d <debuglevei >] f-n <dat&basenuraber>] 

The arguments are the same as for the idi0dhm program. 
8.2*4 The IdiflidlchUdren program 

The Idif2id2children program is normally invoked from ldJ0dbm. It is used to 
convert an LDIF text file into xd2 children and dn2id indexes. Occasionally, it 
may be necessary to run this program yourself; for example if one of these indexes 
has become corrupted. kiij2M2chUdren is invoked like this 

Xdif 2id2children ~i <inputfile> -£ <slapdconf igf ile> 
[~d <debuglevel>] f-n <databasentimber>] 

The arguments are the same as for the ldi0dhm program. Yon can use the Idbmcai 
program to create a suitable LDIF input file from an existing L'DBM database, 

8.2.5 The tdhmcat program 

The Idbmcai program is used to convert an id2 entry index back into its LDIF 
text format This can be useful when you want to make a human-readable backup of 
your database, or as an intermediate step in creating a new index using the 
idif2mdex program. The program is invoked like this: 

Idbmcat I -n] <f ilename> 

where <£il.ename> is the name of the id2 entry index file, The corresponding 
LDIF output is written to standard output 

The -n option can be used to prevent the printing of entry I Ds in the LDIF format. 
If yon are creating an LDIF format for use as input to !dif2mdex or anything by 
IdifSldhm, you should not use the -n option (because the entry IDs must match 
those already in the id 2 en try file). If you are just making a backup of your data, 
you can use the -n option to save space. 

8.2.6 The idif program 

The Idif program is used to convert arbitrary data values to LDIF format This can 
be useful when writing a program or script to create the LDIF file you will feed into 
the ldi0dbm program , or when wri ting a SHELL baekend, Idif takes an attri bute 
name as an argument, and reads the attribute value(s) from standard input. It 
produces the LDIF formatted attribute line(s) on standard output. The usage is: 

Idif [-b] <attrnarae> 
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where <attrname> is the name of the attribute. Without the -b option, Idif 
considers each line of standard input to be a separate value of the attribute. 

The - b option can be used to force Idif to interpret Its input as a single raw binary 
value. This option Is useful when converting binary data such as a jpegPhoto or 
audio attribute. 

8,3 The LDIF text entry format 

The LDAP Data Interchange Format (LDIF) is used to represent LDAP entries in a 
simple text format. The basic form of an entry is: 

[<id>] 

dn: distinguished name> 
< at; t r t y pe > : < a 1 1 rva 1 ue > 
<attrtype> : <at t rvalue > 

where <id> h the optional entry ID (a positive decimal number). Normally ? you 
would uot supply the < idx allowing the database creation tools to do that for you , 
The idhmcat program, however, produces an. LDIF format that includes <id> so 
that new indexes created will be consistent. 

A line may be continued by starting the next line with a single space or tab 
character, e.g., 

dn: cn^Barbara J Jensen, o-University of Michi 
gan , c™U3 

Multiple attribute values are specified on separate lines, e.g., 

en; Barbara J Jensen 
en: Bafos Jensen 

If an <attrvalue> contains a non-printing character, or begins with a space or a 
colon the <attrtype> is followed by a double colon and. the value is encoded 
in base 64 notation, e.g., the value " begins with a space" would be 
encoded like this: 

CXlt i IGJl.Z2lucYB3aXRoXGEgc3BhY2U^ 

Multiple entries within the same LDIF file are separated by blank Hues, Here's an 
example of an L DIF file containing three entries, 

dn; en-Barbara J Jensen, o-University of Michi 

gan, c~US 
an: Barbara J Jensen 
exit Babs Jensen 
ob j ect class : person 
sn: Jensen 

dn.: cn«Bjorn J Jensen, o-University of Michi 
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gan , c~US 
cn: Bjorn J Jensen 
en: Bjorn Jensen 
ob j eetciass ; person 
an : Jensen 

dm cn- Jennifer J Jensen, o«University of Michi 

gan, c~U8 
cn; Jennifer J Jensen 
cn : Jennifer Jensen 
ob j act class : person 
sn : Jensen 

j pegPhot o ; : / 9 j /4 AaQSkZ JKgABAAAAAQASAAD./ 2 wBDABALD 
A4MChA0DQ4 SERATGCgaGBYWGDE j JRO oO j MS PDkzODdASPxOQ 
ERXRTc 4 UG1 RV1 9 i . Z 2 hnPk IxeXBkeFxl Z 2 P / 2 wBDARES EhgVG 



Notice thai the jpegPhoto in Jennifer Jensen's entry is encoded using base 64. 
The kfif program (described in Section 8,2.6) can be used to produce the LDIF 
format 

NOTE-: Trailing spaces are not trimmed from values in an LDIF fife. Nor are 
multiple internal spaces compressed . If you don't want them in y our data, don't pot 
them there . 

8,4 Converting from QUIPU EDB format to LDIF format 

If you have directory data that is or was held in a QUIPU DSA (available as part of 
the ISODE package), you will want to convert the EDB files used by QUIPU into 
an LDIF file, The edhlldif program is provided to do most of the conversion for 
you. Once you have an LDIF file, you should follow die steps outlined in section 
6.2 above to build an LDBM database for slapcL 

8*4*1 The edb2Idif program 

The edb21dif program is invoked like this: 

edb21dif [,-d] [~v] f-r] [~o] [~b <hasedn>] 
[~a <addvaLsf ile>] l>f <f ileafctrdir>3 
[- i <ignoraattr . * « >) [<edhi ±1& < , , >] 

Hie LDIF data is written to standard output. The arguments have the following 
meanings: 

-d 

This option enables some debugging output on standard error, 

-V 

Enable verbose mode thai writes status information to standard error, such 
as which EDB file is being processed, how many entries have been 
converted so far, etc. 
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-r 

Recurse through child directories, processing all EDB files found. 

Cause local . add file definitions to override the global addfi le (see ~a 
below) 

-fa <basedn> 

Specify the Distinguished Name that all EDB file entries appear below. 

- a < addval s f i I e > 

The LDIF information contained in this file will be appended to each entry; 

-f <f ileattrdir> 

Specify a single directory where all file-based attributes (typically sounds 
and images) can be found, If this option is not given, file attributes are 
assumed to be located in the same directory as the EDB file that refers to 
them. 

~i <ignoreattr> 

Specify an attribute that, should not be converted. You can include as many 
- i flags as necessary, 

<edbf xle> 

Specify a particular EDB file (or fibs) to read data from, By default, the 
EDB , root (if it exists) and EDB files In fee current directory are used. 

When edh2ldif h invoked, it will also look for files named „ add in the directories 
where EDB files are found and append the contents of the . add file to each entry . 
Typi.cal.ivv this feature is used to include Inherited attribute values (e.g.. 
objeeiClass) that do not appear in the EDB files. 

8.4,2 Step-by~step EBB to LDIF conversion 

The basic steps to follow when converting your EDB format data to an LDIF file 
are; 

1 , Locate the directory at the top of the EDB file hierarchy that your QU1FU 
DSA masters. The EDB file located there should contain the entries for the 
first level of your organization or organizational unit. If you are- using an 
indexed database with QUIPLL you may need to create EDB files from your 
index files (using the synctree or qh2edh tools). 

2* If you do not have a file named EDB * root in the same directory that 
contains your organizational or organizational unit entry, create it now by 
hand. Its contents should look something like this: 

MASTER 
OOOOOl 

o-University of Michigap 
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object Class- top & organisation & domainRelatedObject &\ 

quipuOfoject & quipuHonLeaf Object 
1= Mm Arbor, Michigan 
Bt^= Michigan 

o« University of Michigan & UMICB & UM & U-M & U of M 
description^ The University of Michigan at Aim Arbor 
associatedDomain^ ixmich.edu 
KiastarDSA- c»US®cn«Woolly Monkey 

3. (Optional) Create a global add file and/or local .add files to take cam of 
adding any attribute values that do not appear m the EDB files. For 
example* if all entries in a particular EDB are person entries and yon want to 
add the appropriate objeetClass attribute value for them, create a file called 
. add in the same directory as the person EDB that contains the single line: 

object Class : person 

4 . Run the edh2ldifprogrmn to do the actual conversion, Make sure you are in 
the directory that contains the root of the EDB hierarchy {the one where the 
EDB * root file resides). Include a -h flag with a base ON one level above 
your organizational entry, and include 4 flags to ignore any attributes that 
are not useful to dapd E.g., the command: 

edb21clif -v -r -b "e~US M -i iattr -i acl -± xaci ~± sacl 
-I lacl - i masterDSA - i slaveDSA > Idif 

will convert the entire EDB hierarchy to LD1F format and write the result to 
a file named Idif , Some attributes that are not useful when running slapd 
are ignored. The EDB hierarchy is assumed to reside logically below the 
base I)N "<HJS'\ 

5. Follow the steps outlined in section 8-2 above to produce an LDBM 
database from your new LDIF file, 

8,5 The Idbmtest program 

Occasionally you may find it useful to look at the LDBM database and index files 
directly (he,, without going through slapd). The Idhmtesl program is provided for 
this purpose. It gives you raw access to the database itself/ idbmtest should he run 
line this: 

Idbmtest [~d <debugievel>3 [~f <sIapdconf igf ile>] 

The default configuration file in the KTCDXR is used if you don't supply one. By 
default idhmtesi operates on the last database listed in the config file. You can 
specify an alternate database, or see the current database with the following 
commands. 

b specify an alternate baekend database 
B print out the current hackend database 

The b command will prompt you for the suffix associated with the database you 
want. The database you select can be viewed and modified using a set of two- letter 
commands. The first letter selects the command function to perform. Possible 
commands and their meanings are as follows. 
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lookup (do not follow indirection) 


T 
Xa 


iOOfvup \TOEiOw muireukmj 


4- 

C 


UavetSC <iUu pilTSl &e\ S ilUu Qm& 


T 




X 


delete an index hem 


e 


edit an index item 


a 


add an index item 


c 


create an index file 


i 


insert an entry into an index item 



The second letter indicates which index the command applies to. The possible index 
selections are as follows, 

c M2ch ildren Index 

d dn2id index 

e id2entry index 

f arbitrary file name 

1 attribute index 

Each command may require additional arguments which idhmiesi will prompt you 
for. 

To exit idhmiest? type control ~D or control - C 

Note that this is a very raw interface originally developed when testing the database 
format It is provided and minimally documented here for interested parties, but it is 
not meant to be used by the inexperienced. See the next section for a brief 
description of the LDBM database format, 

8<$ The LDBM database format 

In normal operation, It is not necessary for you to know much about the LDBM 
database format. If you are going to use the idhmtesf program to look at or alter the 
database, or if you want a deeper understanding of how indexes are maintained, 
some knowledge of how it works could be useful This section gives an overview 
of the database forma t and how skupd makes use of it 

8,6,1 Overview 

The LDBM database works by assigning a compact four-byte unique identifier to 
each entry in the database. It uses this identifier to refer to entries in indexes. The 
database consists of one main index file, called id2 entry, which maps from an 
entry's unique identifier (BID) to a text representation of the entry itself Other 
index files are maintained, for each indexed attribute for example, that map values 
people are likely to search on to lists of El IX 

Using this simple scheme, many LDAP queries can be answered efficiently, For 
example, to answer a search for entries with a surname of si Jensen% sfapd would 
first consult the surname attribute index, look up the value "Jensen" and retrieve the 
corresponding list of EIDs. Next, slapd would look up each BID in the id2 entry 
index, retrieve the corresponding entry, convert it from text to LDAP format, and 
return it to the client, page si 
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The following sections give a very brief o verview of each type of index and what it 
contains. For more detailed information see the paper "An X.500 and LDAP 
Database: Design and implementation," available in postscript format from 

ftp : //terminator , rs . ltd . umich , edu/ldap/papers/xldbm.ps 
8,6,2 Attribute index format 

The LDBM baefcend will maintain one index file for each attribute it is asked to 
index. Several sets of keys must coexist in this file (e.g., keys for equality and 
approximate equality), so the keys are prefixed with a character to ensure 
uniqueness* The prefixes are given in the table below 

~ equality keys 

approximate equality keys 
* substring equality keys 
\ continuation kevs 

Key values are also normalized (e.g., converted to upper case for case ignore 
attributes). So, for example, to look up the surname equality value in the example 
above using the Idhmtest program, you would look up the value "-JENSEN", 

Substring indexes are maintained by generating all possible N -character substrings 
for a value (N is 3 by default). These substrings are then stored in the attribute 
index, prefixed by '** r \ Additional anchors of iiA * and are added at the 
beginning and end of words. So, far example the surname of Jensen would cause 
the following keys to be entered in the index: A JE f JEN, ENS, NSE t SEN, EH$ . 

Approximate values are handled m a similar way, with phonetic codes being 
generated for each word in a value and then stored in the index, prefixed fay 

Large blocks in the index are split into smaller ones. The smaller blocks are 
accessed through a level of indirection provided by the original block. They are 
stored in the index using the continuation key prefix of "\\ 

8*6.3 Other indexes 

in addition to the id2 entry and attribute indexes, LDBM maintains a number of 
other indexes, including the dn2id index and the id2 children index. These 
indexes provide the mapping between a DN and the corresponding EIIX and the 
mapping between an Ell) and die EIDs of the corresponding entry's children, 
respectively; 

The dn2id index stores normalized DNs as keys. The data stored is the 
corresponding E1EX 

'The id2ehiSdren index stores EIDs as keys. The data stored is a list of EIDs, just as 
for the attribute indexes. 
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9. Performance Tuning 



There are several things you can do to tune the peribnnance of dcipd for your 
system. Most of them have to do with the LDBM backend. LDBM uses an index 
mechanism to store and retrieve information In slapcl Bach entry is assigned a 
unique ID, used to refer to the entry in the indexes, A search for entries with a 
surname of 'Mensen*', for example, would look up the index entry ^--JENSEN*' in 
the surname index. The data returned is a list of IDs of entries having that value for 
the surname attribute. We have found several things to be useful in improving the 
performance of this indexing scheme, especially on modify operations, 

9 J The afilDs threshold 

Some index entries become so large as to he useless. For example, if every entry in 
your database is a person entry, the * 4:::: PERSQN" index entry in the ohjectelass 
index contains every entry* This returns very little useful infonnation, and can 
cause significant delays, especially on updates. To alleviate this problem, we have 
in trod uced the idea of an all IDs index entry; 

The aillDs entry stands for a real index entry containing the IDs of every entry in 
the database, hut it takes up very little space, never needs updating, and can be 
manipulated quickly and efficiently . The trade-off is that it does not prune the set of 
candidate entries at all during a search. This must he done using other, more ^high- 
powered" index entries. 

You can set the minimum number of IDs that an index entry may contain before it 
turns into an all IDs block by changing the SLAPD LDBM MIN MAX IDS variable 
in the include /Idapconf 19 >h file. The actual number is determined at 
runtime by the LDBM backend, depending on the block size of the underlying 
device (i.e., the number you provide is rounded up to the nearest multiple of a 
block size). 

9.2 The entry cache 

The LDBM backend can be configured to keep a cache of entries in memory . Since 
the LDBM database spends much of its time reading entries from the i d2 entry 
file into memory , this cache can greatly speed performance. The trade-off is that the 
cache uses some extra memory; The default cache size is 1000 entries. See the 
discussion of ihe caches! se option in Section 5,2.3 on LDBM configuration. 

5.3 The DB cache 

The LDBM backend uses a number of disk-based index files, If the underlying 
hash or B-tree package supports in-memory caching of these files, performance can 
be greatly improved* especially on modifies. Ihe size of this in-memory file cache 
is given by the dbcachesi ze option, discussed in more detail in section 5:23 on 
LDBM configuration. The default dbcachesi ze is 100K. 
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$A Maintain the right indices 



Finally, one of the best performance tune-ups you can. do is to make sure you are 
maintaining the right indices. Too few indices can lead to poor search performance, 
1 oo many indices can lead to poor update performance. For example, the LDBM 
baekend would be perfectly happy to maintam substring and approximate indices 
for the ob j ectclass attribute, but this would not be useful and would just slow 
do wn update operations. If your database has many entries and is handl ing queries 
for substring equality on the surname attribute, you should make sure to maintain a 
surname substring index so these queries are answered quickly* 

So* take a look at the index lines in your slapd configuration file to ensure that 
on!y those indices that make seme and are needed are being maintained. 
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Distributing slapd DATA 

For many sites, running one or more sktptk thai hold m entire subtree of data is 
sufficient But sometimes it niay be desirable to have one slapd re&x to other dapek 
for a certain part of the tree. This can be accomplished by creating a referral entry m 
one slapds database pointing to another sicpd, For those familiar with X.500, a 
slapd referral entry is similar to an X.500 knowledge reference. 

The referral entry acts as a mount point, glueing two slapd databases together. A 
referrai entry has an oh/eeteiass of "referral" and is named by a ref attribute 
containing a URL pointing to the slapd holding the data below the mount point. 
This mechanism is very general and allows slapd databases that are not normally 
hierarchical to be grafted together, 

An example should help illustrate things. Suppose your company is running a slapd 
and just purchased a new company, also running a slapd You can easily connect 
the two databases by creating an entry like this in your stapifs database, 

an ; ref - 5f Idap : //new. host /o^New Company, c«US ,f , o^Your 

company, c^UB 
object class ; referral 

Now any subtree search that has this entry in its scope will return a referral to the 
new company, in addition to any entries matched in your database, Referrabaware 
clients will continue the search at the new company's server, 

A mechanism similar to this is used to support distributed indexing, described in 
Appendix C 
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1 1 . Replication with sfurpd 



In certain configurations, a single slapd instance may be insufficient to handle the 
number of clients requiring directory service via LDAP, It may become necessary to 
nm more than one slapd instance. At the University of Michigan, for instance, there 
are four slapd servers, one master and three slaves, A DNS lookup of the name 
Iciap, itd.umich.edu returns the IP addresses of those four servers, 
distributing the load among them. This master/slave arrangement provides a simple 
and effective way to increase capacity > availability and reliability . 

Slurpd provides the capability for a master slapd to propagate changes to slave 
slapd instances, implementing the master/slave replication scheme described above. 
Slurpd mm on the same host as the master slapd instance, 

11.1 Overview 

Slurpd provides replication services 'in hand". That is, it uses the LDAP protocol 
to update a slave database from the master. Perhaps the easiest way to illustrate this 
is with an example, In this example, we trace the propagation of an LDAP modify 
operation from its initiation by the [.DAP client to its distribution to the slave slapd 
instance. 

Sample replication scenario: 

Step 1 : An LDAP client stalls up and connects to a slave slapd. 

Step 2: The LDAP client submits an LDAP modify operation to the slave 
slapd. 

Step 3: The slave slapd. returns a referral to the LDAP client, which causes 
the client to send the modify operation to the master slapd. 

Step 4: The master slapd performs the modify operation, writes out the 
change to its replication log file and returns a success code to the 
client 

Step 5: The slurpd process notices that a new entry has been appended to 
the replication log file, reads the replication log entry, and sends the 
change to the slave slapd via LD AP, 

Step 6: The slave slapd performs the modify operation and returns a success 
code to the slurpd process. 

Note that if the LDAP client happened to connect to the master slapd to begin with. 
Step 3 is omitted, but the rest of the scenario remains the same , 

11.2 Replication Logs 

When slapd is configured to generate a replication logffie, it writes out a file in a 
format which is a variant of the LDIF format. The replication log gives the 
replication shefs), a timestamp, the DN of the entry being modified, and a series of 
lines which specify the changes to make. In the example below, "Barbara Jensen"* 
has replaced a line of her mukilineDescri ption, "The change is to be propagated to 
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the slapd instance running on truelies,rs,itd,imitch.edu. The lastModifiedBy and 
lasiModified Time attributes are also propagated to the slave slapd. 



replica : trollies . rr> . itd.utaich . edu: 389 
time: 8096X8633 

dn: cn~Barb&ra Jensen., ou^Peqple, o^Uni varsity of; Michigan, c-US 

change type: roodify 

delete ; raul t ILirieDescription 

irailtiLineD^scriptiari: X enjoy sailing irs my spare time 

add; xaultiLifieDescript.ion 
muitlLdr^DescriptiOTi: A dreamer. * . 

delete; lastMcxSif iedBy 

add; lastModifiedBy 

lastModitiecBy: cr^S&rb&ra Jensen, ou^Peopie, ©"University of Michigan, 

cfelete : last»3ii : ied7irfte 

add; lastModifiedTime 
lastModif ieciTxme; S5082S073308Z 



The modifications to last Mod if iedBy and las t Modi fiedTime were 
initiated by the master slapd 

11,3 Command-Line Opticas 

Slurpd supports the following command-line options. 

-d <level> j ? 

This option sets the slurpd debug level to <leval> . When level is a v ?" 
character, the various debugging levels are printed and slapd exits, 
regardless of any other options you give it Current debugging levels (a 
subset of slapd $ debugging levels) are 

4 heavy trace debugging 

64 configuration file processing 

S5535 enable all debugging 

Debugging levels are additive. That is, if you waul heavy trace debugging and want 
to watch the config file being processed, you would set level to the sum of those 
two levels (in this ease, 68), 

f <£ilename> 

This option specifies an alternate slapd configuration file. Slurpd does not 
have its own configuration file. Instead, ail configuration information is 
read from the slapd configuration file. 

-r <£ ilename> 

This option specifies an alternate slapd replication log file. Under normal 
circumstances, slurpd reads the name of the slapd replication tag file from 
the slapd configuration file. However, you can override this with the -r 



flag, to cause slurpd to process a different replication log file. See 
section 10.5, Advanced slurpd Operation, for a discussion of how you 
might use this option, 

Operate in "one-shot*' mode, Under normal circumstances, when slurpd. 
finishes processing a replication log, it remains active and periodically 
checks to see if new entries have been added to die replication log. in one- 
shot mode, by comparison, slurpd processes a replication log and exits 
immediately. If the ~o option is given, the replication log file must he 
explicitly specified with the - r option 

-t <directory> 

Specify an alternate directory for slurpd *$ temporary copies of replication 
logs. The default location is /usr/tmp* 

~fc <f ilename> 

When slurpd uses kerberos to authenticate to slave slapd instances, it needs 
to have an appropriate srvtab file for the remote slapd Hi is option allows 
you to specify an alternate filename containing kerberos keys for the remote 
slapd. The default filename is /etc/srvtab. You can also specify the 
srvtab file to use m the slapd configuration file's repl i ca. option. See the 
documentation on the srvtab directive in section 5:2.2, General Backend 
Options, A more complete discussion of using kerberos with slapd and 
slurpd may be foimd in Appendix EX 

11 A Configuring slurpd and a slave slapd instance 

To bring up a replica slapd msvancc, you must configure the master and slave slqpd 
instances for replication, then shut down the master slapd so you can copy the 
database. Finally, you bring up the master slapd instance, the slave slapd instance, 
and the slurpd instance. These steps are detailed in the following sections. You can 
set up as many slave slapd instances as you wish, 

It*4> 1 Set up the master slapd 

Follow the procedures in Section 4 Building and Installing slapd. Be sure that the 
skpd instance is working properly before proceeding. Be sure to do the following 
in the master slapd configuration file, 

I > Add a replica directive for each replica. The binddn- parameter should 
match the updatedn option in the corresponding slave slapd configuration 
file, and should name an entry with write permission to the slave database 
(e,g,, an entry listed as rootdn, or allowed access via access directives 
in the slave slapd configuration file). 

2, Add a replogf ile directive, which tells slapd where to log changes. 
This file will be read by slurpd. 
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It* 4, 2 Set up the slave slapd 

Install the slapd software on the host which is to be the slave slapd server. The 
configuration of the slave server should be identical to that of the master, with the 
following exceptions: 

1 , Do not include a replica directive, While it is possible to create "chains" 
of replicas, in most cases this is inappropriate* 

2. Do not include a replogf i la directive. 

3* Do include an upda ted!! line. The DN given should match the DN given 
in the binddn- parameter of the corresponding replica- directive in the 
master slapd cmfig file. 

4* Make sure the DN given in the updatedn directive has permission to write 
the database (e.g., it is listed as rootdn or Is allowed access by one or 
more access directives), 

11,4,3 Shut down the master slapd 

In order to ensure that the slave starts with an exact copy of the master's data, you 
must shut down the master siapd. Do this by sending the master siajftd process an 
interrupt signal with kill -TERM <pid>, where <pid> is the process-id of 
th e master slapd process. 

If you like, you may restart the master slapd in read-only mode while you are 
replicating the database. During this time, the master slapd will return an "unwilling 
to perform" error to clients that attempt to modify data. 

H*4.4 Copy the master slapd- s database to the slave 

Copy the master's datahase(s) to the stave. For an LDBM-based database, you 
must copy all index files as well as the "NEXTID* file. Index files will have a 
different suffix depending on the underlying database package used. The current 
possibilities are 

dbfa Berkeley DB B-tree backend 

dbh Berkeley DB hash backend 

gdbrn GNU DBM backend 

pag UNIX NBDM backend 

dir UNIX NBDM backend 

You should copy all files with such a suffix that are located in the index directory 
specified in your slapd eonfig fi le, 

11*4.5 Configure the master slapd for replication 

To configure slapd to generate a replication logfile, you add a ^replica'* 
configuration option to the master slapd $ config file. For example, if we wish to 
propagate changes to the slapd instance running on host truelies.rs.itd.umich.edu: 
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replica host-truelies . rs , ltd . utnich , edu ; 389 

binddn**cn* Replicator, o~U of c*tJS H 
hindme t hod- s imp 1 e credent x al b~ b eo re t 

In this example, changes will be sent to port 389 (the standard LDAP port) on host 
trueiies. Hie slurpd process will bind to the slave slapd as *cn~Replicator , 
o^U of M, c=US" using simple authentication with password "secret" 
Note that the entry given by the fo.inddn« directive must exist in the slave slapct's 
database (or be the rootdn specified in the slapd config file) in order for the bind 
operation to succeed , 

11*4. 6 Restart the master slapd and start the slave ^lapd 

Restart the master slapd process. To check that it is generating replication logs, 
perform a modification of any entry in the database, and check that data, has been 
written to the log Hie; 

11,4.7 Start slurpd 

Start the sfarpd process- Slurpd should immediately send the test modification you 
made to the slave slapd* Watch the slave slapd logfite to be sure that the 
modification was sent, 

slurpd -f <masterslapdconf igf ile> 
11.5 Advanced slurpd Operation 

11-5*1 Replication errors 

When slurpd propagates a change to a slave slapd and receives an error return code, 
it writes the reason for the error and the replication record to a reject file. The reject 
file is located in the same directory with the per-replica replication iogfile, and has 
the same name, but with the siring *\ rey appended. For example, for a replica 
running on host trueiiesTs.itdaimieh.edu, port 389, the reject file, if it exists, will 
be named 

/usr/tmp/ trueli es , rs . ltd , umich > edu : 389, 
A sample rejection log entry follows; 

ERROR; fSb such attribute 

replica c trueligs , rs . itd„ umich . edu: 389 

th&& t 8 0 9 £ 1 8 6 3 3 

dn: cn^Barbara Jensen, ou^People, o^Qniversity of. Michigan, oUS 

change v.ype : iraxii £ y 

deles&e : mil v.ildnel^Bcicipt:loxi 

TmltiXiiiii&X)£3£i-±ptia$rii 1 sn:ioy sailing in my spare time 

add; TSMaltiT^ineDescription 
rriultiLirieDescriptiori: A drsaffier. , . 

delete: la&tModit'i&dSy 

add : I astModi t i edBy 

la^t^odifi^dBy: cn«B&rbar^j^§@n, ou-P&opls, o-University of Michigan, 



delete : lastMociif iecffime 



sckh XaatMoclif iedTime 



Note that this is precisely the same format as the original replication log entry, but 
with an ERROR line prepended to the entry; 

11.5.2 Slurpd** one-shot mode and reject files 

It h possible to use slurpd to process a rejection log with its "one-shot mode;' In 
norma! operation, siurpd watches for more replication records to be appended to the 
replication log file. In one-shot mode, by contrast, slurpd processes a single log 
file and exits. Slurpd ignores ERROR lines at the beginning of replication log 
entries, so if s not necessary to edit them out before feeding it the rejection log. 

To use one-shot mode, specify the name of the rejection log on the command line as 
the argument to the -r flag, and specify one-shot mode with the -o flag. For 
example, to process the rejection log file 

/usr/brsp/replog. true lies . rs , ifcdL umicfo* edu: 389 and exit use the 
command 



11.$ Replication from a siapd directory server to an X.500 DSA 

in mixed environments where both X.500 DSAs and slapd are used, it may be 
desirable to replicate changes from a J directory server to an X.500 DSA. This 
section discusses issues involved with this method of replication, and describes the 
currently-available facilities. 

To propagate changes from a siapd directory server to an X.500 DSA. slurpd runs 
on the master slapd host, and sends changes to an ktapd which acts as a gateway to 
the X.500 DSA; 



slurpd - r /usr/tmp/truelies * rs . itd.utnich, edu; 389 -o 
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Figure 6: Replication from slapd to an £500 DSA 



Note that the X.500 DSA must be a read-only copy. Since the replication is one- 
way, updates from DAP clients connecting to the X,500 DSA simply cannot be 
handled. 

A problem arises where attribute names differ between the slapd directory server 
and the X.500 DSA. At present, slapd and slurpd do not support selective 
replication of attributes, nor do they support translation of attribute names and 
values. For example, durpd will attempt to update the "modifiersNmne" and 
"modify FimeStamp** attributes on the slave it connects to- However, the X.500 
DSA may expect these attributes to be named i 1astModifledBy M and 
"UstModiiledTirne". 

A solution to this attribute naming problem is to have the Idapd read oidtahSes thai 
map "modiflersNaroe" to the ohjectlD (01 D) for the 'lastModifiedBy" attribute and 
"modifyrimeStamp" to the OlD for the J lastModifiedI1me n attribute. Since attribute 
names are carried as OIDs over DAP, this should perform the appropriate 
transl ation of attribute names. 
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12, Appendix A: 



Writing a slapd Backend 



Slapd has a front end that handles connection management access control, and 
protocol interpretati oa and a number of backends that handle database operations. 
The two pieces eomnumicate through a well-defined APL This section documents 
that API for programmers who want to write their own database backend, and 
describes the steps necessary to integrate a new backend with slapd 

Here's a quick overview of the steps you should follow to create a new backend for 
slapd. 

1 , Choose a name for your backend (we'll call it f oo) and create a new directory 
in the slapd source area (servers/ slapd/) called back-foo. This 
directory will contain the Backend routines you are about to write. You should 
also create a Make -temp late file in this directory. See the other Make- 
template files in the various back- * / directories for examples. 

2, Write backend routines for each function you want your backend to provide. 
See the next section for details on how to do this and the API your routines 
should export. You should prefix your backend routines with "fboj" to ensure 
uniqueness, Your backend will undoubtedly want to call some of the utility 
routines described in section A/2, 

3 , Edit the file servers/slapd/backend,c to add declarations for the backend routines 
you wrote in step 2, and to initialise a backend structure. Take a look at the 
existing definitions in that file for other backend s. 

12.1 The slapd Backend API 

The slapd backend API (SLAP!) consists of twelve calls. Nine of the calls 
correspond to the nine LDAP protocol operations bind, unbind, search, compare, 
modify, modify RDN, add, delete, and abandon. The other three calls are to 
initialize the backend, shut down the backend, and handle backend-specific 
configuration. Bach call is described in detail below. The first nine routines are 
passed the same first three parameters; 

Backend *be /* info about this backend */ 
Connection *conn/* info about this connection */ 
Operation *op /* info about this operation */ 

lire other parameters depend on the call itself, 

12.1/1 Bind 

The SLAPI bind routine is defined as follows. 
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foo_bind { 

Backend *he, 
Connect ion *conn , 

Operation *op, 
char *dxx, 
int. method^ 
struct berval * creel 

) 

The fu st three parameters are as defined above. The remaining parameters are 
dn The distinguished name to hind as, 

method The authentication method to use. It should he one of the 
Map, h constants 

LDAP J\UTH_S IMPL.E 
LDAP_AUTH_KRBV4 1 
LDAP_AUTH_KRB V4 2 

ered The credentials for the bind (either a password or Kerberos 

credentials)* 

The bind routine should return a value of 0 if the hind is successful* nonzero 
otherwise. This is important as a return of 0 will cause the front end to consider the 
connection authenticated, and it. will base subsequent access control decisions 
assuming the DN supplied is authentic. 

Things to note: 

* If the length of the credentials supplied for simple authentication is zero, a 
NULL bind is being requested, This should succeed. 



# 



If a cl ient sends a NULL dn, a N ULL bind is also requested. Thi s situation is 
handled by the front end, so yon will never see it. 



12.1.2 Unbind 

The SL AP! unbind routine is defined as follows. 

foo_unfoind( 

Backend *be , 
Connection *conn, 
Operation *op 

} 

The only three parameters are the common parameters defined above. The 
connection will be dropped by the front end. The unbind baekend routine is 
provided so the hackend can do any clean-up of local information it has pertaining 
to the connection, 

12. 1*3 Compare 

The SLAPi compare function is de^ie^s follows. 
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f oo_compare { 

Backend *foe, 
Connect ion *conn, 
Operation *op, 
char *dn, 
Ava *ava 

} 

The first three parameters are the eontmori ones described above. The other 
parameters are 

6x\ The distinguished name of the entry on which to perform the 

compare. 

ava The attribute value assertion to test against the entry. 

The AVA structure is defined as follows, 

typed ef struct ava { 

char *ava type ; 

struct berval ava_value; 
} Ava; 

The type to compare is given in the ava_type field, and the value to compare is 
given in the ava value field. 

12.1.4 Search 

The SL API search routine is defined as follows. 

too search ( 

Backend *be , 
Connection *conn, 
Operation *op, 
char *hase, 
int scope, 
int siselimit, 
int time limit, 

Filter *f liter, 
char *f ilterstr , 

char **afctrs , 

int attrsonly 

) 

The first three parameters are the common ones described above. The rest of the 
parameters axx? 

base The DN of the base obj ect at which to start the search. 

scope The scope of the search. One of the I dap * h constants 

LDAPJSCOPEJ3ASEOSJECT 
LDAPJ3COPEJDNELEVEL 
LDAP S COPE SUBTREE 
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si delimit A client-supplied limit on the number of entries to return. A 
value of zero implies no Limi t 

t imel imi t A client-supplied limit on the number of seconds to spend on 
the search. A value of zero implies no limit. 

filter A data structure representing the search filter. A baekend 
would normally use either this parameter or the filterstr 
pammeier, not both, See below for a description of this 
structure. 

filterstr A string representation of the search Biter, A baekend would 
normally use either this parameter or the filter parameter, 
not both. The format of this string is as defined in RFC 
1588, 

attrs An array of char *\s indicating the attributes to return 

from the search. A NULL value for attrs implies all 
attributes. 

attrsonly A Boolean parameter indicating whether only attribute types 
should be returned (non-zero) or if attribute types and values 
should be returned (zero). 

The Filter structure is used to represent an LDAP search filter, The seareh filter is 
described in ASN.l as the following. 



Filter ; :« CHOICE { 



and 


[0] 


SET OF Filter, 




m 


SET OF Filter, 


not 


[23 


Filter , 


equal ityMateh 


£3] 


AttributeYalueAsserfcion, 


substrings 


E4] 


Sub stringFilte r , 


9 r e at e r 0 r Equa I 


is] 


A 1 1 r i bu t e Va I u a A s s e r t i oxi , 


lessOxEqual 


16} 


Att ributeVaXueAssertion, 


present 


m 


AttributeType, 


approxMatch 


m 


AttributeValueAssertioxi 



! 

The C language Filter structure definition used to represent this via the filter 
parameter is defined as follows in fee sl ap . h header file. 
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typectef struct filter | 

ims igned long f cho ice ; 
union { 

char 

Ava 

struct f lit 
struct sub 

char 

char 

char 

char 
} £_un_stib; 
} f _un ; 

#def ine f type f ___un , f ...un 

#def ine f _ava f jra > f __un_ 

#def iae £ avtype f_un , f un 

#define f_avvalua f_un, njm 

#de f i ne f _and f jun „ f un 

# def ine f _or £_"un * £_ Ui \ 

# define f_not f_im,£_uxi 

# de fine £ 1 i s t f un , f un 

#def ine £_sub £ un.f un 

#def ine f_sub_type f_un. f _ui\ 

#de£ine f^sufo^initiai i : _un . f jn^ 

Me fine £_sufo_any f _un , f un 

#de fines f_sub_fin«l f_un,f_un^ 

struct filter *f next ; 



from Idap/h 



*£_unj:.ype /* present */ 
f_un_ava ; / * eq, approx , le, ge * / 
er * f _un_comp lex ; / * and , or , not * / 

{ / * substrings * / 

*£ _unj3uh_typa * 

* f _un_Bufo_ini t ial ; 

* * f __un__Bub_any ; 
*£ un sub final; 



type 
ava 

ava , ava_type 

ava ,ava_value 

complex 

complex. 

complex 

complex 

sub 

sub . f _un_sub_type 
sub , j: _un_s ub_ i x\i t i a X 
sub , f un suh any 
&ub , £_un_sub_£inal 

/* in and/ or chain */ 



The f choice field will have one of the following values, defined m the Map.h 
header file. 



LDAP FILTER AMD 
LDAF^FILTER^OR 
LDAP JF I LTER_NOT 
LDAP_F X LTER_EQUAL 1 T Y 
LDAP FILTER SUBSTRINGS 
LDAF_FILTERJ3E 
LDAP_FX LTER_LE 
LDAP_P I LTER JPRESEOT 
LDAP _F I LTER^APPROX 

12*1.5 Modify 



Hie Si API modify function is defined as follows, 

foo_modify { 

Backend *tae , 
Connection *conn, 

Operation *op, 

char *dn, 

LDAPMod *mods 

) 



The first three parameters are the common ones described above. The other 
parameters are p 3ge m 



dn The distingui shed name of the entry to modify, 

mods The list of modifications to make to the entry. 

The LDAPMod structure is defined as follows in the Idap . h header file, 

typedef struct Idapmod { 
int rood op ; 
char *mod_type ; 
union ( 

char * * modv_s t r va 1 s ; 

struct foervai * *modvJbval s ; 
} mod^vals ; 
#define mod values mod vals*modv strvals 
#def ine modjovalues mod_vals .modv_bvals 

struct Idapmod *mod_next ; 
} LDAPMod ; 

The modjsp field identifies the type of modification and will have one of the 
following values, defined in the Idap . h header file, 

LDAP MOD .ADD 
LDAP^MOD^DELETE 
LDAP MOD REPLACE 

Note that the mod fo values form of representing values is always used, but that 
the mod_op field is not ORed with LDAP_MOD_B VALUES > as LDAP clients must 
do to use the mod b values field. 

12*1.6 Modify RON 

The SL API modify RDN function is defined as follows. 

f oo_modi fyrdn ( 

Backend *foe, 

Connect ion *conn. 

Operation *op, 

char *dn, 

char *newrdn, 

int deleteoldrdn 

) 

The first three parameters am the common ones described above. The other 
parameters are 

dn The distinguished name of the entry whose name is to be 

changed. 

newrcfo The new RDN to give the entry, 
deleteoldrdn 

A Boolean flag indicating whether the old RDN is to he 
deleted from the entry (non-zero) or kept as a non- 
distinguishe^ttg^ute value in the entry (zero). 
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12.1,7 Add 



The SLAP! add ftroetion is defined as follows, 

f oo add { 

Backend *be f 
Connection *conn, 
Operation *op, 
Entry *e 

} 

The first three parameters are the common ones described above. "The additional 
parameter is 

e A pointer to an Entry structure specifying the entry to add* 

The Entry structure is defined in the slap,h header file as follows. 

typedef struct entry { 
char *e dn ; 

Attribute *e_attrs ; 

/* other things you should not mess with */ 
} Entry; 

The ej3n field contains the DN of the entry. 

The e_attrs field is a linked list of the entry's attributes. Each element of this list 
has the following definition, as given in slap . K 

typedef struct attr { 

char *a_type ; 

s t rue t berva 1 * * a_va 1 s ; 

int a_ syntax; 

struct attr *a next; 

} Attribute; 

The ajsyntax field identifies the syntax of the attribute and will have one of the 
following values, defined in slap , h. 

SYNTAX C I S / * ca s e insens it ive s t r i ng * / 
3YNTAX_CES/* case sensitive string ^ */ 
SYNTAX BIN/* binary data */ 
SYFPAXJTEL/* telephone number string */ 
SYNTAX DN /* dn string */ 

The syntax values may be additive in some cases. For example, an attribute of type 
telephoneNumber will have syntax {syntax_cis | syntaxjtel) . 

12.1.8 Delete 

The SLAPI delete function is defined as follows. 
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foo_delete ( 

Backend *foe, 
Connection *conn, 
Operation *op, 
char *dii 

) 

The first three parameters are the common ones described above. The additional 
parameter is 

dn The distinguished name of the entry to delete, 

12* 1*9 Abandon 

The SLAPI abandon function is defined as follows. 

f oo_abandon { 

Backend *be, 
Connection *conn, 
Ope r a t i on * op , 
int id 

) 

The first three parameters are the common ones defined above. The additional 
parameters is 

id the message identifier of the request to be abandoned . 

In addition, the front end will set the o abandoned flag in the operation* s 
Operation structure, Backends niay check this flag periodically to see if the 
operation has been abandoned. 

12.1,10 Initialization 

When a new backend instance is encountered in the s/apd configuration file, the 
corresponding SLAPI initialization routine is called. It k defined as follows. 

f oo_init { 

Backend *be 

) 

The sole parameter is 

be Tlie baekend-specilic data structure. 

The be parameter is used to hold backend-specific information. It is as defined in 
the beginning of this section in the slap , h header tile, if your backend needs to 
keep any information specific to a backend instance, it should put it in the 
be private field of the be parameter. 

12. J /II Configuration 

When a configuration option unknown to the front end is encountered in a database 
definition in the slapd configurat^^, it is parsed and passed to a backend- 
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specific conjuration routine for processing. The SLAP! backend-speciffc 
configuration routine Is defined as follows, 

foo_con.fi g { 

Backend *be, 

int. 1 ineno, 

int argc, 

char **argv 

) 

I he parameter are 

be The baekend-speeifie data structure defined above. 

1 ineno The current line number in the configuration file, This is 
useful if an error message has to be printed, 

argc The number of arguments from the configuration file line. 

argv The list of arguments from the configuration file tine. 

12.1.12 Close 

When slqpd exits normally, it calls a close routine provided by each baekend 
database, allowing the backends to clean up and shut down properly; The SL AP! 
close routine is defined as follows. 

foo_elose ( 

Backend *be 

) 

The sole parameter is 

be The backend-specific data described above. 

1 2.2 Utility Routines Your Backend May Want to Calf 

There are several utility routines provided for dealing with various data types, 
sending results and errors to clients, etc., that your backend will likely want to call 
Some of the more common and useful routines are described here. 

12* 2.1 Sending Search Entries 

The send_search_entry() routine is used to encode a search result entry and send it 
back to the client. It is defined as fallows* 

sena_search_e:ntry ( 
Backend *be, 
Connection *conn, 
Operation *op, 
Entry *e, 
char **attrs , 

int attrsonly 

) 
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The first three parameters are the common ones passed to the haekend routines. The 
entry to send back is given in e> An array of attribute types to include from the entry 
(subject to access control) is given in'attrs. The attrsonly parameter determines 
whether attributes only or attributes and values should be sent back, 

12*2/2 Sending a Result 

An LDAPResuIt is sent to the client by calling the seii4J<i^jnssultO routine, 
defined as follows. 

send_ldap_result f 

Connection *conn f 
Operation *op, 
int err, 
char * mat chad , 

char *text 

) 

The first two parameters are two of the three common parameters passed to the 
haekend. The err parameter is the LDAP error code to pass back, it should be one 
of the codes defined idapJi, The matched parameter should onSv be non-NULL if 
err is set to LDA1^NC)^SUCIK)BJEC1\ In this case, matched gives the DN 
prefix of the request that was resolved successfully. The final parameter, text is an 
arbitrary siring sent back to the client. It is meant to contain a helpful error message, 

12*2.3 Testing a Filter Against an Entry 

Often, your baekend may need to test an entry to see if it satisfies a given search 
filter. The test jfikerO routine is provided for this purpose, 

test_£ liter ( 

Backend *be f 
Connection *conrt 
Operation *op, 
Entry *e, 
Filter *f ilter 

} 

The first three parameters are the common ones. Hie e parameter is the entry to 
match against the filter, given in the filter parameter. testjfiherQ returns zero if the 
entry matches the filter, non-zero otherwise, 

12.2.4 Creating an Entry 

Two routines are provided to convert between the LDiF text entry format and the 
internal representation, They are 

str2entry ( 

char *s 

) 

where s is the string containing the LDIF entry; and 
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entry2str { 

Entry *e, 
int *len, 
int print id 

) 

where len will contain the length of the string returned, and pr int id indicates 
whether the entry ID should be printed in the LDIF format, The string returned 
should be considered a pointer to static storage that is overwritten on each call 
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13. Appendix B: 



Writing a SHELL backend 



This section provides infonnation for system administrators wanting to use the 
SHELL backend to slapd. it explains the Input format, output format and calling 
conventions a SHELL backend program most follow to communicate with slapd. 

13.1 Qv&rview 

When slapd recei ves an operation to a SHELL backend, the backend consults the 
information given in the slapd configuration file to determine what program to 
invoke to handle the operation. For example, if the SHELL database definition in 
tire configuration file contained a Sine like this 

search /usr/ local /bin/ search, sh 

The indicated command would be invoked in response to a search request. 

Slapd feeds a text representation of the request to the command on the command's 
standard input. Slapd then reads a text representation of the results or errors 
produced by the command from the command's standard output. These text results 
are converted to LDAP format and returned to the client. Slapd pays attention to the 
exit status of the command in some situations (i.e., to determine if a BIND request 
has succeeded or not). 

The next sections discuss those input, output and exit conventions in more detail 

13.2 Input Format 

The input to your SHELL backend program is a simple text-based, newline 
separated sequence of <option>: <value> pairs conveying the type and 
information in a request. The exact format for each request is given below. All 
requests start with a key word indicating the type of request, a rasgid; line 
indicating the unique message ID of the operation, and one or more suffix : lines 
indicating the database suffix(es) the backend is configured for, 

13.2.1 Bind 

The input format for a BIND request is as follows. 
BIND 

msgid; < integer > [suffix: <dn>3 + 
dn: <binddn> 
method : < int eger > 
eredlen : < integer > 
cred: < credentials 

The msgid parameter is a unique identifier for the operation. The method 
parameter will be one of the LDAP autheniieation methods listed in <ldap»h>. 
The only credential currently supported is a clear-text password (used with a simple 
bind). 
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1 3*2.2 Unbind 



The input format for an UNBIND request is as follows. 
UBBIND 

msgid : < integer> 
[suffix: <dn>] + 
dm <binddn> 

This routine is provided so the baekend can do any clean-up necessary. 
13*2,3 Search 

The input format for a SEARCH request is as follows. 



SEARCH 

msgid ; <integer> 
[suffix: <dn>] * 
base ; <haseoh j ectdn> 
scope; 0 j 1 j 2 



sizel.itn.it : <integer> 
time limit : < integer > 
filter ; <ldap£ liter > 
attrsonly: 0 j 1 
attrs : all j <attrlist> 

The values of the s cop e parameter correspond to the various LDAP scopes listed 
in <ldap .h>. 

The values of the deref parameter correspond to the various LDAP dereference 
options Hsied in < Idap . h>. 

The f ilter parameter is a string representation of the LDAP search filter* as 
described in RFC 1 588, 

The <attrlist> is a space-separated list of attributes to retrieve, 
13.2*4 Compare 

The input format for a COMPARE request is as follows. 
COMPARE 

msgid: < integer > 
[suffix; <dn>] + 
dm <entrydn> 
<attrtype> : <attrvalue> 

fhe AVA (attribute value assertion) to compare to the entry is given in the 
< at t r t ype > : < a t t rval ue > line. 
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13.2.5 Modify 

Hie input format for a MODIFY request is as follows. 
MODIFY 

msgid : < integer> 
[suffix: <dn>] + 
dm <entrydn> 
[add; <attrtype> 

[<attrtype>: <att rvalue] +] * 
[delete : <attrtype> 

[<attrtype> ; cattrvalue] *] * 
[replace : <attrtype> 

[<attrtype> : <attrvalue] +J * 

The add, delete and replace constructs indicate the modifications to make. 

13.2.6 Modify RON 

The input format for a MODIFY RDM request is as follows. 
MODRDN 

msgid : <integer> 
[suffix: <dn>] + 
6xi t <entrydn> 
newrdn: <rdn> 
deleteoldrdn: 0 j 1 

The deleteoldrdn parameter is a Boolean parameter (where 0 means false and 1 
means true), 

13.2.7 Add 

The input format for an ADD request is as follo ws, 
.ADD 

msgid : < integer > 
[suffix: <dn>] + 
<entry> 

The <enfcry> parameter is a text representation of the entry to add in L DIF format, 
as described in Section 63, 

13*2.8 Delete 

The input format for a DELETE request is as follows. 
ADD 

msgid : < integer > 
[suffix: <dn>] f 
dm <entrydn> 
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13*2.9 Abandon 



The input format for an abandon operation is as .follows. 
ABANDON 

msgid : < integer> 
[suffix: <dn>] + 

For the abandon operation, the msgid parameter gives the message ID of the 
operation to abandon. 

13.3 Output Format 

There are two possible results a SHELL backend command can produce: search 
entries, and results. The format of each is described belo w, 

13.3. 1 Search Entry 

The format of a search entry is the LDIF format described in Section 63. Multiple 
entries can be given by separating the entries by blank lines. The idif program 
described m Section 8.2,6 can be very helpful in producing the LDIF format 
required by the SHELL backend, 

13.3.2 Result 

The format of a result is as follows, 
RESULT 

code : < i n t e ge r > 
matched ; <part ialdn> 
info : <string> 

All of the parameters are optional and will be given default values if omitted. If 
search entries have been returned, the RESULT follows the last one, with a blank 
line preceding the RESULT, 

1.3*3.3 Debugging 

A SHELL- backend command may produce debugging statements which may be 
Jogged but otherwise ignored by slapci. Any output line beginning with the 
characters "DEBUG;" will be treated as a debugging statement by slopd. 

This feature can be useful when trying to debug a problem with your SHELL 
backend. If you turn on SHELL debugging in slapd (level 1024), it wili log 
anything it reads from a SHELL backend, allowing you to see your backend's 
debugging statements easily, 

1 3*4 Exit Status 

SHELL backend commands should be mindful of their exit status. This status is 
examined by the invoking slopd to determine- whether the command succeeded or 
not. This can be important for a mp^ef 0 gf reasons. 



1 . For modify operations, the exit status determines whether the modification 
should be logged and sent out to replicas or not 

2, For bind operations, the exit status determines whether the hind was 
successful, and therefore whether the DN given should he trusted on future 
access control decisions. 

An exit status of zero indicates the command was successful A. non-zero exit status 
indicates the command was not successful 

Note that on a bind operation, a zero exit status indicates that the DN given in the 
bind should he trusted on future access control decisions. This means that ifl for 
example, a NO AUTH bind (no password provided) succeeds, you should be sure 
not to return an exit status of zero. 

13,5 Example 

The following example illustrates a simple use of the SHELL backend to provide 
LDAP access to the /etc/passwd file on a machine, 

13.5,1 Configuration file 

Our example makes use of the following simple configuration file, 

referral Idap : / / I dap , itd. umich.edu 

database shell 

suffix ' 1 o ------ un i v e r s i t y of michigan, c ------ us" 

sea rch / usr / 1 oca 1 / bin/ s e a r chexamp 1 e . sh 

This configuration defines a single SHELL backend, for entries in the 
'^University of Michigan, c=US w subtree, Requests involving any 
other subtree will be sent to the LDAP server running on the host 
Idap. itd* umich.edu, A search operation will cause the command 
/usr/ local /bin/ sea rehexample . sh to be executed. Any other operation 
will result in an '"unwilling to perform* error being returned to the client, 

13*5*2 Search command shell script 

The search command in our example is implemented by tire following houme shell 
script. It assumes a very simple filter of the form (uid»login) where login is a 
user's UNIX login. It extracts the login from the filter, does a simple grep for it in 
the /etc/passwd file, and parses the resulting line (if any) using owk to pull out 
the geeos field. 

Note that our simple example does no error checking, handles only very simple 
Otters, ignores the scope, sizelimit, timel imit and other parameters, and 
is meant for illustrative purposes only. A real example should do more error 
checking and handle more situations. 
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I , #! /bxn/sh 

2 * while [ 1 ] ; do 

3* read TAG V&LUE 

4 . if [ $? ~ne 0 j ; then 

5 . break 

6. fi 

7. ease "$TAG" in 

8 . base : 5 

9 . BASE- $ VALUE 
10. ;; 

II , f liter: } 

12, FILTER« $ VALUE 

■i 3 » / / 

14 . esac 

1 5 , dona 

16 . LOGIN*" echo $ FILTER j sed -a * sf , **\ { . *\) } 1 v 

17. PWLlNE^ v grep ~i wA $LOGIN" /etc/passwd" 

18. if [ $? -01; then 



19. echo "DEBUG : passwd line is $PWLINE B 

20. echo $PWLINE j awk ~F : ' { 

2 1 . pr int f { H dn : cn= % s f Is \n w , $ 1 , base } ; 

22. print f ( w cn: $1} ; 

23. print f ("en: %s\n tt , $5} ; 

24. print f ( ff sn: %s\n H , $1) ; 

25. print f ("uid: %s\n", $1} ; 

26. } ? basew"$BASE tt 

27. echo 



28 . fi 

29. echo "RESULT" 

30. echo "code: 0" 
31. . exit 0 

The line numbers are for illustrative purposes only and do not appear in the actual 
file. 

Note the debugging statement on line 1.9- The output from this statement is ignored 
by siopd because of the DEBUG ; prefix, unless debugging is turned on, in which 
ease It may be logged (depending on the debugging level) but will otherwise not 
affect the search results sent. 
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14, Appendix C: Distributee! Indexing with centipede 



centipede is the LDAP ceniroid index generation and maintenance program* You 
can use it to extract ceniroid or other index information from one LDAP server and 
install it in another. Although index information can be extracted from any LDAP 
server, only a slapd LDAP server will understand the information and thus be 
capable of making use of it as indexing information (i.e., yon should only attempt 
to Install index information in & slapd LDAP server), centipede is very experimental 
at the moment so use it at your own risk. 

Why would you want to do this? If you want to support searches whose scope 
cannot be easily restricted using the LDAP namespace, centipede can make these 
searches efficient For example, what if you are looking for Babs Jensen, but yon 
don't know what company she works for, or even what state she's in. All yon 
know is that she is a US resident A search of the entire c ::: US subtree may be what 
you want to do, but that's potentially very expensive since it involves contacting 
every server in the US, With centipede? an indexing siapd can use the index 
information centipede provides to prune the search space of servers, only referring 
the client to servers likely to have information on Babs, Or, you might want to 
create a special index area in your LDAP tree that collects centipede information 
Ironi other servers based on some entirely different criteria not related to the 
hierarchy of the LDAP namespace, 

T he general form of a centipede command is as follows, 

STCDIR/centipede [-f filter] [~F3 [~R] [-£ filter] 
|>t directory] [~m authmethod] [-b binddn] 
Op passwdj Oc cachesizej 
-s sourceurl 
-d dasturl 
attributes 

The options have the following meanings. 

Turn on verbose mode. This option can be given multiple times to increase 
the level of verbosity. 

Do not : actually install index information. Useful in conjunction with -v for 
seeing what centipede is up to, 

- f idapf liter 

Specify a filter used to select the entries for which to generate indexing 
information. Idapf liter should be a string LDAP fitter as described by 
RFC 1588. 

-F 

Generate full, as opposed to relative, index information. 
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--R 

Generate relative, as opposed to full, index information. Full mfomiation is 
still, generated If there is no previous information available from which to 
generate the relative information* This is the default 

-t directory 

Specify the directory m which to create temporary files, find existing index 
information, and put new index information. The default is whatever is used 
by lempnamQ), 

-fa binddn 

Speeify the ON to authenticate with when extracting index information, 
■p passwd 

Speeify the password to use for simple authentication when extracting index 
information. 

»m authmethod 

Speeify the authentication method to use when extracting index information, 
authmethod should be either "simple" or u kerberos n . 

-B foinddn. 

Specify the DIM to authenticate with when installing index information, 

-P passwd 

Specify the password to use for simple authentication when installing index 
information. 

-M authmethod 

Specify the authentication method to use when installing index information, 
authmethod should be either "simple" or "kerheros". 

~c cache size 

Specify the size in bytes of the cache used when building the new index 
information* Upping this number can cause a big performance boost, if 
youVe got the memory for it 

14.1 An Example 

Suppose you are running an LDAP server on the host babs.com lor an 
organization called "BabsCo* based in the US, and you want to participate in the 
c=US indexing scheme described above by generating index information for the 
cru sn and ofo j ect class attributes in all the people entries in your subtree. You 
want to insiail the index informaiioin in the indexing slapd running on the host 
vertigo, rs. ltd, umich.edu under the c~US entry; This way, when an 
LDAP client connects to the slqpd on vertigo and does a subtree search of 
c~U3, slapdcm consult the index information to tell whether it should refer the 
client to vour server or not. You could accomplish this with a command like this: 
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$ (ETCDIR) /centipede -f ' (objectclass-person) ' 

~m simple -h < you r - root dn > ~p <your~rootdnpw> 
~s "Idap ■: / /babs . coin/o~BabsCo , c~US" 
-d " Idap : / / vert igo , rs*itcL untich . edu/c-US tJ 
en sn objectclass 

Note the - b and ~p options can be used to authenticate as an entity able to read ail 
the information you want. 

14:2 Limitations 

This is all very experimental at the moment and is subject to change. The scheme is 
very promising, but lots of stuff needs to he worked out such as how clients 
discover indexing servers, how indexing servers discover index sources, how best 
to maintain the information, etc, 

Currently, eemipede only handles value-based index information, A future version 
of centipede will allow other types of index information to be manipulated (e.g.. 
woid-hased indexes, substring indexes, phonetic indexes, hash indexes, etc.), A 
future version may also allow weights to be generated for the index values. 

Finally* centipede works strictly over LDAP at the moment. If and when the 
Common Indexing Protocol develops, centipede may change to use OF instead. 
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15, Appendix D: Using Kerberos authentication with 
siapd and slurpd. 



Slojid and sltwpd both support authentication using MIT's Kerberos 4 system, 
which is supported in the LDAP protocol as a stronger form of authentication than 
simple (clear-text password) authentication. This appendix describes how to 
configure slapd and slurpd to support Kerberos 4 authentication, and how to link 
Kerberos identities to directory entries. Note that some LDAP clients do not 
support Kerberos authentication. 

15 A Build the U-M LDAP Package with Kerberos Support Enabled 

By default Kerberos support is not included when you build slc^?d and slurpd as 
part of the U~M LDAP package. You will need to edit the Make - common file to 
enable Kerberos before you make the software. See section 4 above far 
instructions on building the LDAP package. 

15:2 Using Kerberos with slapd 

Follow these steps to configure slapd for Kerberos authentication. 
IS. 2. 1 Obtain a srvtab File for Your sfapti Server 

You will need to add your slapd server to your realm's Kerberos server and extract 
an appropriate srvtab (service key) file. This is typically done using MIT's 
kdh edit and exf jrvtab utilities, and must be done by someone who has privileged 
access to the Kerberos database (the Kerberos administrator). 

You will actually want to add two Kerberos entries for each slapd server; one with 
a name portion of Idapserver and one with a name portion of xS 0 Odsa, The 
second one is necessary because most LDAP clients that use Kerberos have no way 
of knowing that they are connected to a server thai is not back-ended by an X.500 
DSA, so they will try to authenticate in two steps, first using to the LDAP server 
and then to the X.500 DSA. slapd will ignore the second authentication step* but 
the LD AP clients will be unhappy if the xSOOdsa principal does not exist. 

The instance portion of both principals needs to match the first part of the real name 
of the host on w hich you run slapd. L DAP clients will determine the real name of 
the slapd host by performing a reverse (gethostbyaddr~style or "in- 
addr , arpa' ') Domain Name Service lookup on the IP address of the slapd host, 
and then they will use the part to the left of the first dot Q as the Kerberos instance 
name for the server. 

For example, if an LDAP client is told to connect to the server on the host 
c 'd.rsJtd*umfch.edu% it wilt perform a forward (gethostbyname-styie) DNS 
lookup and open a TCP LDAP connection to IP address 1 4 L21 1.164.2 port 389, 
When doing Kerberos authentication, it will look up the hostname using the IP 
address and see that the real host name is terminator * rs * itd < umxch , edu» 
Thus the Kerberos tickets (shown in name. instaxaca@re aim fomiat) that the 
client wilt obtain and pass to siapd will be: 
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Idapserver , teminator#umich , edu 

and 

x50 Odsa , terminator&aimieh . edu 

(assuming that **umich . edu" is your Kerberos realm). Both of these principals 
need to be added to the "umich , edu" Kerberos database, and a srvtab file would 
need to be extracted that contains their service keys, 

1 5*2.2 Install the srvtab File and Tell slapd Where It 1$ 

Piace the srvtab file on the machine where you are going to run sfoprf and add a 
"srvtab" line to the slapd configuration file. The srvtab eonfig. file option 
simply contains the foil path to the **ldapserver/x500dsa w service key file 
obtained in the previous step (the default is /etc/ srvtab if no srvtab option is 
specified). For example, assuming the srvtab is in a file called 
/etc/ slapd , srvtab, this would he an appropriate slapd coafig. file line: 

srvtab /etc/slapcL srvtab 

If slapd is already running, you will need to kill and restart it to have slapd 
recognize the new option. 

15,2,3 Add Kerberos Names to Entries to Enable Authentication 

To authenticate as an entry in the directory using Kerbeors, the entry must contain 
one or more krbName (Kerberos Name) attributes that associate a Kerberos 
identity with the entry. Bach krbName value should be a string of the form; 

principal . inst&nce&re&lm 

(the instance part is optional). For example, to allow the principal "b j ensen* in 
the "uroich . edu" Kerberos realm to authenticate to slapd as the entry "cn^Babs 
Jensen, o~University of Michigan, e~OS'\ you could use the 
Idapmodif y(l) tool (or another LDAP client) to add a krbName attribute to her 
entry that has the string value "hjensen@umich* edu* To do this, first you 
would first create a file called /tmp/mociify with the contents: 

cn^Babs Jensen, o^Universxty of Michigan, c«US 
krbK&me^b j ensen&utnich , edu 

and then, use a command like this to actually make the change: 

Idaptaodify ~f /tmp/modify -D ** cn«Hanager , o™University of 
Michigan, c^US M -w secret 

Note thai the above command assumes that you have set rootdn to 
^cn^Manager, o^Uxiiversity of Michigan, c**US s * and rootpw to 
"secret" in your slapd configuration file, 

You should now be able to authenticate to slapd as Bab's entry using Kerberos, 
For example, the following commands will authenticate using Kerberos and 
perform a search for all entries thai have a surname of "Smith" while bound: as 
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Babs* entry and retrieve the commonJTame of each entry (text you would type is 
whown in bold): 



kin i t b j ensen 

University of Michigan (terminator . rs , ltd, umich.edu} 
Kerberos Initialization for "bjensen" 
Password : secret 

1 daps e arch ~fc * l cn»Babs Jensen, o~ University of 

Michigan* c»US K sn«smi th on 



15*2.4 Associate a Kerberos Name with the "rootdit*' (optional) 

If you want to me Kerberos to authenticate as the slapd root do (the special I5N 
that is not suhjeet to access control or administrative limits), you should add a 
rootkrbname directive to the slapd config. file. For example, if bjensen 
should have the ability to authenticate as the rootdn when she authenticates to 
Kerberos using an instance of "admin", you would include a Sine like this in the 
slapd config. file: 

rootkrbname b j ensen , admixi^umiah , edu 

15.3 Using Kerberos With slurpd 

Slurpd (the replication daemon) is capable of using Kerberos authentication when 
authenticating to the slave slaf>ds thai it is configured to serve, To enable this 
feature, follow these steps; 

15-3, t Obtain a srvtab File for Your siurpd Server 

Create a Kerberos principal entry in your realm's Kerberos database for slurpd. 
The name and instance can be anything you like (unlike the "Idapserver 9 * and 
kC x50Gcisa" principals you must use for slapd). You will need to obtain and install 
a srvtab file that contains this slurpd Kerberos key (install it on the machine where 
slurpd will run). As mentioned above, you will need to contact your Kerberos 
administrator to get this file. For the examples that follow, we wil l assume thai you 
have added a Kerberos database entry and obtained a srvtab file for the principal: 
slurpd . terminator@umich . edu and installed it in a file called 
/etc/slurpd . srvtab 

15.3.2 Configure the siapd Slaves to Accept Kerberos Authentication 

Each slapd slave must be compiled and configured to support Kerberos 
authentication (as discussed previously). In addition, the updatedn used by 
slurpd to authenticate when sending updates to the slaves must have a Kerberos 
Name associated with it that matches the slurpd srvtab file obtained in the previous 
step. This can be done as for any other entry simply by adding the appropriate 
fcrbName attribute value to the updat edn entry in slapd, If you happen to be 
using the rootdn as the updatedn, then you can just include an appropriate 
rootkrbname directive in the slapd eonfig, file, e.g.. 
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rootkrbname slurpd , terminator^umich , edu 

15*3.3 Configure slurpd to Use Kerberos When Connecting to the Slaves 

You need to use a bincfeethod of kerfoeros and specify the path to an 
appropriate srvtab file within the replica configuration file options. You will 
also need to specify the path to the srvtah file. E.g., 

replica host-Slav*! , umich . edu 

*binddn=cn=Manag<er, o«Ttoiver9ity of Michigan, c=US" 

bindmathod^kerheros 

Brvtab«/etc/slurpd . srvtab 

Don't forget to restart both slurpd m& the siapd slaves after making changes to the 
config. fiie(s). 
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1 !. RELATED PROCEEDINGS APPENDIX 

[37 CPR41.37(c)(l)(x)) 

There have been no decisions rendered by a court or the Board in any 
proceeding identified pursuant to paragraph (c)(1)(H) of 37 CFR 4137(c)(1). 
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